home *** CD-ROM | disk | FTP | other *** search
/ The Arsenal Files 6 / The Arsenal Files 6 (Arsenal Computer).ISO / os2 / blt2_205.zip / BULLET2.INF (.txt) < prev    next >
OS/2 Help File  |  1996-02-26  |  266KB  |  10,905 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. Copyright ΓòÉΓòÉΓòÉ
  3.  
  4. 26-Feb-1996 
  5.  
  6.           BULLET is Copyright 1992-96, and is owned by the author, Cornel Huth, 
  7.           and is protected by United States copyright laws and international 
  8.           treaty provisions.  License restrictions apply. 
  9.  
  10.  
  11. ΓòÉΓòÉΓòÉ 2. License Agreement ΓòÉΓòÉΓòÉ
  12.  
  13. Before using this software, BULLET/2 (or simply, BULLET) you must agree to the 
  14. following: 
  15.  
  16.    1. A BULLET/2 license grants you the right to use the BULLET/2 library code 
  17.       on a royalty-free basis according to the terms of this License Agreement. 
  18.  
  19.    2. You are not permitted to operate more than one copy of this software 
  20.       package at one time per license.  For example, if you have ten 
  21.       programmers that have access to the BULLET/2 package at the same time, 
  22.       you are required to have ten BULLET/2 licenses. 
  23.  
  24.    3. There is no restriction on the number of users you may support, and no 
  25.       restriction on the number of different end-user programs you may 
  26.       distribute that use BULLET/2.  You may allow any number of simultaneous 
  27.       users to use your end-user program. 
  28.  
  29.    4. The dynamic link library, BULLET2.DLL, may be distributed with your 
  30.       end-user program.  No other BULLET product may be distributed without 
  31.       permission (for example, you may not distribute Bullet's import library, 
  32.       BULLET2I.LIB). 
  33.  
  34.    5. You are not permitted to distribute non-executable code containing 
  35.       BULLET/2 code.  This means that may not redistribute BULLET/2 with your 
  36.       program if your program can be used by other programmers to develop 
  37.       executable code.  BULLET/2 must be part of an end-user product only. 
  38.       This means that you cannot provide an overlay or other such external code 
  39.       containing BULLET/2 code if that code is to be used as a programming 
  40.       library for other programmers, from which the other programmers can 
  41.       create programs.  If you require distributing a non-end-user package 
  42.       containing BULLET/2, you must obtain written permission from the author. 
  43.       This limitation pertains to the distribution of BULLET/2 library code. 
  44.       You may, however, develop and distribute your programmer package (ie 
  45.       non-end-user) as you wish, but you may not distribute BULLET/2 library 
  46.       code with that package without written permission.  For example, you may 
  47.       develop class libraries that use the BULLET/2 library code, and 
  48.       distribute those tools that you have written, but you may not include 
  49.       BULLET/2 library code, or BULLET/2 activation methods, in that package. 
  50.       The programmer using your package would need a BULLET/2 license to make 
  51.       use of your package. 
  52.  
  53.    6. The static link library, BULLET2.LIB, may not be distributed except in 
  54.       executable form as a component in your executable program (EXE). 
  55.       BULLET2.LIB may not be placed into a DLL.  BULLET2.LIB, if part of your 
  56.       license/Option, may only be linked directly to your end-user program. 
  57.       BULLET2.LIB is available with Option C licenses only. 
  58.  
  59.    7. Shareware use is limited to 28 days, and for the sole purpose of 
  60.       evaluating the software.  The BULLET/2 library code may not be 
  61.       distributed in any form without a registered BULLET/2 license.  A 
  62.       BULLET/2 license is obtained only with purchase of a BULLET package, 
  63.       purchased from an authorized BULLET distributor (see Order Information). 
  64.  
  65.    8. A BULLET license is specific to the option level purchased.  License 
  66.       holders with a lower Option may not use any higher level Option code. 
  67.       For example, if you find another product using the Option C DLL, and you 
  68.       have an Option A license, you are not permitted to use the Option C DLL 
  69.       in your development, nor may you distribute any code that is not part of 
  70.       your Option level. 
  71.  
  72.    9. Your end-user program using the BULLET/2 DLL is required to be a 
  73.       copyrighted work, and must contain a valid copyright notice in the form, 
  74.       'Program-name Copyright (C)Year Your-Name', or similar.  No notice of 
  75.       BULLET's copyright need be further specified in your program (in other 
  76.       words, you don't need to mention BULLET, but you may if you wish).  This 
  77.       applies only if you distribute the BULLET/2 DLL with your product. 
  78.       Programs that are linked using the BULLET2.LIB static link library need 
  79.       not display a copyright notice.  In other words, if you must distribute 
  80.       to the Public Domain, where no copyright is desired for your program, you 
  81.       must link using the static link library, and not the DLL. 
  82.  
  83.   10. BULLET/2 is owned by the author, Cornel Huth, and is protected by United 
  84.       States copyright laws and international treaty provisions.  You are not 
  85.       permitted to make copies of this software except for archival purposes. 
  86.  
  87.   11. You may not rent or lease BULLET/2. You may not transfer this license 
  88.       without the written permission of the author.  If this software is an 
  89.       update or upgrade, you may not sell or give away previous versions. 
  90.  
  91.   12. You may not reverse engineer, decompile, or disassemble this software if 
  92.       the intent or result is to alter the software. 
  93.  
  94.   13. There are no expressed or implied warranties with this software. 
  95.  
  96.   14. All liabilities in the use of this software rest with the user. 
  97.  
  98.   15. U.S. Government Restricted Rights.  This software is provided with 
  99.       restricted rights.  Use, duplication, or disclosure by the Government is 
  100.       subject to restrictions as set forth in subparagraph (c)(1)(ii) of the 
  101.       Rights in Technical Data and Computer Software clause at 52.227-7013. The 
  102.       software is owned by Cornel Huth/6402 Ingram Rd/San Antonio Texas 
  103.       78238/USA.  This agreement is governed by the laws of the Great State of 
  104.       Texas, the United States of America, and all other countries of Earth. 
  105.  
  106.  Any questions concerning this License Agreement should be directed to me at 
  107.  any of the addresses listed in Product Support. 
  108.  
  109.  Note:  Failure to comply with any part of this License Agreement immediately 
  110.  terminates any and all licenses that you may have to use BULLET/2. 
  111.  
  112.  
  113. ΓòÉΓòÉΓòÉ 3. Installation ΓòÉΓòÉΓòÉ
  114.  
  115. Installation instructions are located in the README text file included with 
  116. your package. 
  117.  
  118.  
  119. ΓòÉΓòÉΓòÉ 4. Product Support ΓòÉΓòÉΓòÉ
  120.  
  121. Support for licensed users is available at my BBS, The 40th Floor, 7 days a 
  122. week.  Hours are 5pm to 9am, Central Time (USA, -0600 GMT (-0500 
  123. April-October).  Weekend BBS hours are 24 hours (5pm Friday to 9am Monday). 
  124. Hours other than above are voice.  A fax can be sent during the times the BBS 
  125. is operating.  Limited technical support for licensed users is also available 
  126. through e-mail (see e-mail address below).  Please use the Bug Report Form when 
  127. reporting possible bugs. 
  128.  
  129. Note:  Technical support is reserved for licensed users.  Those evaluating 
  130. Bullet are supported for the Bullet installation only.  Complete support is 
  131. available once you register. 
  132.  
  133. BBS: +1(210)684-8065 (times listed above), N-8-1. 
  134.  
  135. The latest in-version (2.x) release of BULLET/2 is always available for free 
  136. download by registered users ($10- by mail).  Bugs, if re-creatable, are fixed 
  137. within 24 hours.  Also available at the BBS are other shareware 
  138. try-before-you-buy products by me, such as the DOS32/Win/NT versions of Bullet; 
  139. the Ruckus/DOS soundcard toolkit; the linear programming optimizer LP; 
  140. interesting 'Specs', and more still.  Current shareware versions are available 
  141. at several sites, with the FTP site listed below being the primary distribution 
  142. point. 
  143.  
  144. My E-mail address: 
  145.  
  146. cornel@crl.com
  147. (FTP) ftp.crl.com /users/co/cornel
  148. (WWW) ftp://ftp.crl.com/users/co/cornel
  149.  
  150.  
  151. ΓòÉΓòÉΓòÉ 4.1. Bug Report Form ΓòÉΓòÉΓòÉ
  152.  
  153. When requesting support for possible bug(s) you must follow these steps (always 
  154. use the current version of the software, and read the product Bulletin/Errata 
  155. if available): 
  156.  
  157.    1. Include a complete problem description. 
  158.    2. Include sample source of the problem, if necessary (99 lines or less). 
  159.    3. Include necessary data files, include files, etc. (no 3rd-party 
  160.       DLL/LIBs). 
  161.    4. Include step-by-step procedure to follow in order to recreate the 
  162.       problem. 
  163.  
  164.  Once done, ZIP it up and upload to the appropriate conference (or to the 
  165.  e-mail address, in uuencoded form).  There, leave a summary and the filename 
  166.  of the ZIP uploaded (or e-mail message).  Tech support does not start on 
  167.  reports unless all steps above are completed.  All files must be included, 
  168.  including the Bullet DLL you are using, header files, etc., so that a compile 
  169.  can be done in an empty directory without changes (no paths added, etc.). 
  170.  
  171.  The goal is for you to minimize the possibility that the bug is in fact your 
  172.  doing.  The best way to ensure this is to remove all extraneous source, and to 
  173.  isolate the problem to a specific sequence of operations.  It must be done in 
  174.  99 lines or less.  If the problem is recreated, it is fixed within 24 hours. 
  175.  
  176.  Note:  For non-bug reports, compose your query and post to the conference (or 
  177.  e-mail).  Off-line composing is recommended.  See the Main Board Bulletin for 
  178.  exact details (if applicable). 
  179.  
  180.  Unregistered users are not supported except for basic install information. 
  181.  
  182.  
  183. ΓòÉΓòÉΓòÉ 5. Ordering Information ΓòÉΓòÉΓòÉ
  184.  
  185. To order Bullet by check, bank check, money-order, or cash, use form 
  186. !ORDER.FRM.  For credit card order, use form !ORDER.CC. 
  187.  
  188. Payment Options 
  189.  
  190. Γûá Check, money-order, cash 
  191.  
  192. Funds must be in US Dollars and must be drawn on a US bank (complete with bank 
  193. routing numbers).  If sending currency, use Registered AirMail.  Personal 
  194. checks require 10 working days to clear. Most major foreign banks have branch 
  195. banks in the US and this can be used for US Dollars/US bank requirements. 
  196. Direct wire-transfer is not available.  Send payment and order form !ORDER.FRM 
  197. to: 
  198.  
  199.    Cornel Huth
  200.    6402 Ingram Rd
  201.    San Antonio, Texas 78238-3915
  202.    USA
  203.  
  204. Γûá Credit card 
  205.  
  206. For credit card orders (Visa, MC, Amex, Discover), call (800)242-4775 (outside 
  207. US, call 1(713)524-6394), or fax to 1(713)524-6398, or via CompuServe e-mail to 
  208. 71355,470 (or internet e-mail to 71355.470@compuserve.com), requesting 'Bullet 
  209. for OS/2' (item# 11185). Include the completed credit card order form when 
  210. using e-mail or fax. 
  211.  
  212. Phone orders are taken during business hours, which for PsL is weekdays from 
  213. 7AM to 6PM, USA Central Time (7AM to 12:30PM on Friday).  Fax or CompuServe 
  214. orders are accepted at any time. 
  215.  
  216. Credit card ordering can be done through the mail by writing to PsL/PO Box 
  217. 35705/Houston TX 77235-5705/USA. 
  218.  
  219. Note:  This is for ordering Bullet; do not use these numbers for any other 
  220. purpose!  Be sure to specify 'Bullet for OS/2' and your license option, as 
  221. shown in the schedule below.  Your shipping address should be the same as your 
  222. billing address for fastest processing.  Fax or postal orders should use order 
  223. form !ORDER.CC.  Please type, or print using large characters.  Double-check 
  224. your information to make sure it is correct.  Incomplete or inaccuarate order 
  225. information requires that I contact you to request that you re-order. 
  226.  
  227. Order Options 
  228.  
  229. Price for your Bullet license is based on this schedule: 
  230.  
  231. Option A is $ 99 for 2-process/100 open files per process, DLL 
  232. Option B is $198 for 32-process/250 open files per process, DLL 
  233. Option C is $297 for unlimited-process/1024 open files per process, DLL and LIB 
  234.  
  235. The BULLET2.DLL may be distributed with your end-user program.  There are no 
  236. run-time fees and there are no royalty fees.  Refer to the LICENSE AGREEMENT 
  237. for limitations on distributing BULLET2.DLL with a non-end-user package. 
  238.  
  239. Γûá Option A is for most programmers.  It permits two processes to use the Bullet 
  240. DLL at the same time.  This is not a user limit, but a process limit.  Two 
  241. processes means that you can start two different programs that use BULLET2.DLL, 
  242. and have them both run at the same time, on the same machine.  Before starting 
  243. a third program that uses BULLET2.DLL, you must end one or both of the previous 
  244. two.  Most programmers should need only 1 Bullet process active at a time. 
  245. There's an extra process should you need it.  The total number of open Bullet 
  246. DBF and index files may be up to 100 files per process, total (sum of data and 
  247. index; memo files are not counted against this).  Most programmers should not 
  248. need more than 100 files open at the same time.  Documentation includes the 
  249. online version, and an ASCII text suitable for printer output.  Standard 
  250. AirMail shipping cost is included in the price.  For US/Canada Express Mail on 
  251. Option A, add $16 (foreign delivery, add $21).  The printed reference manual is 
  252. available with Options B and C only. 
  253.  
  254. Γûá Option B permits 32 processes to use the Bullet DLL at the same time.  The 
  255. total number of open Bullet DBF and index files may be up to 250 files per 
  256. process, total (sum of data and index; memo files are not counted against 
  257. this).  Documentation includes the online version, an ASCII text suitable for 
  258. printer output, and the printed Reference Manual.  US/Canada shipments are made 
  259. using USPS Express Mail.  Foreign shipments are made using International 
  260. Express Mail.  Express Mail shipping cost is included in the price. 
  261.  
  262. Γûá Option C permits an unlimited number of processes (limited only by the OS 
  263. itself) to use the Bullet DLL at the same time.  In addition to the BULLET 
  264. dynamic link library (BULLET2.DLL), Option C provides the BULLET/2 static link 
  265. library (BULLET2.LIB), which may be directly linked into your end-user 
  266. executable program so as to not require BULLET2.DLL.  The total number of open 
  267. Bullet DBF and index files may be up to 1024 files per process, total (sum of 
  268. data and index; memo files are not counted against this).  Special-order 
  269. versions with more than 1024 files are available.  Documentation includes the 
  270. online version, an ASCII text suitable for printer output, and the printed 
  271. Reference Manual.  US/Canada shipments are made using USPS Express Mail. 
  272. Foreign shipments are made using International Express Mail.  Express Mail 
  273. shipping cost is included in the price. 
  274.  
  275. Delivery Options 
  276.  
  277. Standard AirMail is 3-5 days for US destinations, and 5-14 days for 
  278. international destinations (standard shipping for Option A).  Express Mail is 
  279. next-day to most US destinations, and two-day to most Canadian destinations. 
  280. International Express Mail is 3-5 days.  Disk media is 3.5-inch, 1.4MB unless 
  281. requested otherwise.  Express mailings are shipped with two identical disk 
  282. sets.  Options B and C always ship Express Mail or International Express Mail. 
  283.  
  284. Note:  All foreign shipments may go through your country's Customs.  Each 
  285. package is valued at the total price of the order, less shipping costs, if any, 
  286. unless pre-arranged otherwise.  Your Customs Office may delay mail delivery if 
  287. duty is required.  Direct download of the registered, licensed version is 
  288. available from the Bullet BBS for the absolute fastest delivery. 
  289.  
  290. Licensed Bullet versions may be download directly from the support BBS.  To do 
  291. this:  1) Order Bullet; 2) Call the BBS and tell me (SysOp) that you've ordered 
  292. Bullet; 3) Upon receipt of your order, I'll leave you detailed instructions on 
  293. getting your licensed version via BBS download.  Shipment of your package will 
  294. still be made, unless you specify otherwise. 
  295.  
  296. Click here [Γûá] for the check, money-order, cash order form. 
  297.  
  298. Click here [Γûá] for the credit card order from. 
  299.  
  300.  
  301. ΓòÉΓòÉΓòÉ 5.1. Order Form for Check, Money-order, or Cash ΓòÉΓòÉΓòÉ
  302.  
  303. Printing this section from here may not fit on a single page.  Use the file 
  304. !ORDER.FRM instead, or select the 'Services' menu item from here (upper-left), 
  305. and select 'Copy to file' to print this to .\TEXT.TMP.  Your e-mail address can 
  306. be used instead of a fax number. 
  307.  
  308. Bullet/2 2.0 for OS/2 Order Form for Check, Money-order, or Cash
  309. Details on Options A-C are in 'Ordering Information' in the documentation.
  310.  
  311.                                     Cost Per    Number of
  312.                                     License     Licenses    Extended
  313.  --------------------------------------------------------------------
  314.  Option A.  Single-license, 2 processes/100 files per process DLL
  315.             Includes AirMail.       $  99.00  x          =
  316.                                                  ------     ---------
  317.      Standard AirMail, for all>         0.00 |
  318.      For Express Mail, USA/Canada>     16.00 |select one
  319.      For Express Mail, all others>     21.00 |           =
  320.  ------------------------------------------------------     ---------
  321.  Option B.  Single-license, 32 processes/250 files per process DLL
  322.             Includes Express Mail.  $ 198.00  x          =
  323.  ------------------------------------------------------     ---------
  324.  Option C.  Single-license, unlimited processes/1024 files per process
  325.             DLL and static link library
  326.             Includes Express Mail.  $ 297.00  x          =
  327.  ------------------------------------------------------     ---------
  328.         For Texas shipping destinations only, add 7.75%  =
  329.                                                             ---------
  330.                                                    TOTAL =
  331.                                                             =========
  332.  
  333. Send TOTAL payment on check (US Dollars/US bank), money-order, or cash to
  334.  
  335.         CORNEL HUTH                       Always endorse your letter
  336.         6402 INGRAM RD                             AirMail
  337.         SAN ANTONIO TX 78238-3915          if you are not in the USA
  338.         USA
  339.  
  340.            PLEASE PRINT - For comments use back and mark here [  ]
  341.  
  342. Your Name>
  343.            -------------------------------------------------- (required)
  344.  
  345.   Company>
  346.            -------------------------------------------------- (optional)
  347.  
  348.   Address>
  349.            -------------------------------------------------------------
  350.  
  351.  
  352.            -------------------------------------------------------------
  353.  
  354.  
  355.            -------------------------------------------------------------
  356.  
  357.  Telephone                       Fax                      Disk
  358.    Number> --------------------- No.> ------------------- Size> --------
  359.  
  360.      Sign>                                    Today's Date>
  361.            ----------------------------------               ---/----/---
  362.  
  363.  
  364. ΓòÉΓòÉΓòÉ 5.2. Order Form for Credit Card ΓòÉΓòÉΓòÉ
  365.  
  366. Printing this section from here may not fit on a single page.  Use the file 
  367. !ORDER.CC instead, or select the 'Services' menu item from here (upper-left), 
  368. and select 'Copy to file' to print this to .\TEXT.TMP.  Your e-mail address can 
  369. be used instead of a fax number. 
  370.  
  371. Bullet/2 2.0 for OS/2 Order Form for Credit Card         (PsL Item# 11185)
  372. Details on Options A-C are in 'Ordering Information' in the documentation.
  373.  
  374.                                     Cost Per    Number of
  375.                                     License     Licenses    Extended
  376.  --------------------------------------------------------------------
  377.  Option A.  Single-license, 2 processes/100 files per process DLL
  378.             Includes AirMail.       $  99.00  x          =
  379.                                                  ------     ---------
  380.      Standard AirMail, for all>         0.00 |
  381.      For Express Mail, USA/Canada>     16.00 |select one
  382.      For Express Mail, all others>     21.00 |           =
  383.  ------------------------------------------------------     ---------
  384.  Option B.  Single-license, 32 processes/250 files per process DLL
  385.             Includes Express Mail.  $ 198.00  x          =
  386.  ------------------------------------------------------     ---------
  387.  Option C.  Single-license, unlimited processes/1024 files per process
  388.             DLL and static link library
  389.             Includes Express Mail.  $ 297.00  x          =
  390.  ------------------------------------------------------     ---------
  391.         For Texas shipping destinations only, add 7.75%  =
  392.                                                             ---------
  393.                                                 TOTAL =
  394.                                                             =========
  395.  
  396. Call this in by telephone voice @ 1(800)242-4775 or 1(713)524-6394, or
  397. fax this to 1(713)524-6398, or Compuserve e-mail to 71355,470, or
  398. internet e-mail to 71355.470@compuserve.com.  For mail address see docs.
  399.  
  400.    PLEASE PRINT - For comments add a separate page and mark here [  ]
  401.  
  402. Your Name>
  403.            -------------------------------------------------- (required)
  404.  
  405.   Company>
  406.            -------------------------------------------------- (optional)
  407.  
  408.   Address>
  409.            -------------------------------------------------------------
  410.  
  411.  
  412.            -------------------------------------------------------------
  413.  
  414.  
  415.            -------------------------------------------------------------
  416.  
  417.  Telephone                       Fax                      Disk
  418.    Number> --------------------- No.> ------------------- Size> --------
  419.  
  420.  Credit
  421. Card Type> ---------- Number> ----------------------------- Exp> ---/---
  422.  
  423.      Sign>                                    Today's Date>
  424.            ----------------------------------               ---/----/---
  425.  
  426.  
  427. ΓòÉΓòÉΓòÉ 6. Tutorial ΓòÉΓòÉΓòÉ
  428.  
  429. This tutorial describes how to set up a basic database.  It describes file 
  430. layout and how to use Bullet to enter into and read from the database.  It does 
  431. not describe aspects that do not relate to Bullet, such as how to load list 
  432. boxes, create dialogs, etc.  This tutorial creates a music CD collection 
  433. database. 
  434.  
  435. The tutorial follows. 
  436.  
  437.  
  438. ΓòÉΓòÉΓòÉ 6.1. Tutorial: Output Requirements ΓòÉΓòÉΓòÉ
  439.  
  440. The goal of this tutorial is to create a database for a music CD collection. 
  441. The method used is a suggested method; it is by no means the only way to 
  442. develop a database, and only touches the surface of database programming.  That 
  443. said... 
  444.  
  445. The most important thing to do is to know what output you want.  From that, you 
  446. know what input is needed.  For the 'CD database', I've drawn up a list of 
  447. things that I want: 
  448.  
  449. Title, artist, and year.  Must have those.  Track name (the song name), track 
  450. number, and play time would be essential, too.  How about who was playing on 
  451. the track and instruments they used?  Put that on your list -- it's not on this 
  452. one. 
  453.  
  454. All these could be entered into a single file as a single database record, but 
  455. that would be a pretty poor design.  A single data file may seem to be the 
  456. obvious way, but in the long run, it's not very good at all.  This database 
  457. uses two data files.  This concept -- multiple data files -- is especially 
  458. useful when the database is more complex.  For example, an accounting system 
  459. would employ many physical data files.  It could be done in one, sure, but the 
  460. maintenance would be very difficult. 
  461.  
  462. Two tables are used:  The Title-Artist-Year table (Title/CTAY), and the 
  463. TrackNumber-TrackName-Time table (Tracks/CTTT).  A table is a file composed of 
  464. rows and columns.  A row is a record; a column is a field.  No two rows may be 
  465. exactly alike (what would be the point?).  In addition to the fields listed 
  466. (the Title, Artist, and Year, for instance), each table includes a Code field. 
  467. TrackNumber is included as a field value in the second table since the physical 
  468. ordering of rows cannot be used for this purpose (it could, technically, but it 
  469. is unwise to depend on row order being preserved since there is nothing 
  470. enforcing the physical ordering of records). 
  471.  
  472. The Code field for the Title table (CTAY) is generated by the program and is 
  473. composed of the first 4 characters of the Title, plus the first 4 characters of 
  474. the Artist, plus the year (all four characters of it).  This code is also used 
  475. in the Tracks table (CTTT).  This serves two purposes:  First, it ensures that 
  476. each Track record is unique (with pretty good certainty; without it, it is 
  477. possible that TrackNumber-TrackName-Time alone may occur more than once), and 
  478. second, it can be used as the primary key when being accessed through the 
  479. foreign key in the Title table (see Record Layout Diagrams).  By searching CTAY 
  480. (the Title Table) for a desired title, or artist, or even year, and using the 
  481. Code field from that row, you can match it to the Code in CTTT (Track Table) to 
  482. find the tracks that belong to that title row (or artist, or year -- whatever 
  483. the search was based on).  To speed up searching, indexes are maintained and 
  484. used for lookups.  For a very large CD collection (say, several thousand CD 
  485. titles, and tens of thousands of tracks), the database can still be very 
  486. quickly queried for whatever information you need (and have programmed). 
  487.  
  488.  
  489. ΓòÉΓòÉΓòÉ 6.2. Tutorial: Record Layout ΓòÉΓòÉΓòÉ
  490.  
  491. The Code field is generated by your program.  Other fields are input data.  The 
  492. following are the data record layouts of the DBF files (tag fields not shown). 
  493. The time field may be created as a text field with the form "mm:ss", or could 
  494. even be made into a 'seconds' field.  This database uses the more direct 
  495. "mm:ss" since that's how it's read off the CD. Note that this information is 
  496. already stored digitally on the CD itself (running time), but that would 
  497. require additional coding and is not relevant to this tutorial (but oh, how 
  498. sweet it could be). 
  499.  
  500.  CTAY TABLE
  501. ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  502. Γöé   CODE     Γöé      TITLE      Γöé     ARTIST      ΓöéYEAR Γöé
  503. Γöé            Γöé                 Γöé                 Γöé     Γöé
  504. ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  505.  MexiConc1993  Mexican Moon      Concrete Blonde  1993
  506.  No NCran1994  No Need to Argue  Cranberries, The 1994
  507.  MachDeep1972  Machine Head      Deep Purple      1972
  508.  
  509.  
  510.               CTTT TABLE
  511.              ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  512.              Γöé    CODE    ΓöéTRKΓöé     TRACKNAME      ΓöéTIME Γöé
  513.              Γöé            Γöé   Γöé                    Γöé     Γöé
  514.              ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  515.               MexiConc1993  01 Jenny I Read         05:18
  516.               MexiConc1993  02 Mexican Moon         05:03
  517.               MexiConc1993  03 Heal It Up           04:21
  518.               MexiConc1993  04 Jonestown            06:06
  519.               MexiConc1993  05 Rain                 03:28
  520.               MexiConc1993  06 I Call It Love       05:15
  521.               MexiConc1993  07 Jesus Forgive Me     05:17
  522.               MexiConc1993  08 When You Smile       04:18
  523.               MexiConc1993  09 Close To Home        03:31
  524.               MexiConc1993  10 One Of My Kind       03:55
  525.               MexiConc1993  11 End Of The Line      04:39
  526.               MexiConc1993  12 Blind Ambition       06:10
  527.               MexiConc1993  13 Bajo La Lune         05:07
  528.               No NCran1994  01 Ode To My Family     04:30
  529.               No NCran1994  02 I Can't Be With You  03:07
  530.               No NCran1994  03 Twenty One           03:08
  531.               No NCran1994  04 Zombie               05:06
  532.               No NCran1994  05 Empty                03:26
  533.               No NCran1994  06 Everything I Said    03:53
  534.               No NCran1994  07 The Icicle Melts     02:54
  535.               No NCran1994  08 Disappointment       04:14
  536.               No NCran1994  09 Ridiculous Thoughts  04:31
  537.               No NCran1994  10 Dreaming My Dreams   03:37
  538.               No NCran1994  11 Yeat's Grave         02:59
  539.               No NCran1994  12 Daffodil Lament      06:09
  540.               No NCran1994  13 No Need To Argue     02:56
  541.               MachDeep1972  01 Highway Star         06:05
  542.               MachDeep1972  02 Maybe I'm A Leo      04:51
  543.               MachDeep1972  03 Pictures Of Home     05:03
  544.               MachDeep1972  04 Never Before         03:56
  545.               MachDeep1972  05 Smoke On The Water   05:40
  546.               MachDeep1972  06 Lazy                 07:19
  547.               MachDeep1972  07 Space Truckin'       04:31
  548.  
  549.  
  550. ΓòÉΓòÉΓòÉ 6.3. Tutorial: Index Files Used ΓòÉΓòÉΓòÉ
  551.  
  552. The index files created for this database are, for CTAY: Title+Artist and 
  553. Artist+Title (the + indicates a compound key made up of more than one field); 
  554. for CTTT: Code+TrackName and TrackName+Code.  With these indexes, searching can 
  555. be made on CD title, by Artist, or by TrackName.  If searching by year is 
  556. required, an additional index could be used, such as Year+Artist+Title (Title 
  557. being used as part of the key in case an Artist releases more than one title in 
  558. a year). 
  559.  
  560. To search by CD title, a title is used as the key.  Even a partial title can be 
  561. used during the actual lookup.  For example, 'Mexican'.  From this, a search is 
  562. made in the Title+Artist index.  The first key starting with 'Mexican' is 
  563. returned.  The index can then be traversed to find any other keys also starting 
  564. with this (by getting the next key).  Since Bullet has high-level access 
  565. routines (GET_FIRST_XB, for example), where a key search returns the data 
  566. record, once a key is found its data is already in memory (the record is 
  567. typically read directly into a structure variable you have set up).  This lets 
  568. you move through the CTAY file getting each record in key order, one at a time 
  569. (one key and record per call to Bullet). 
  570.  
  571. With the data record in memory, the Code field in the record (CTAY table) is 
  572. used as a foreign key into CTTT.  A new search needs to be done, this time on 
  573. the Code+TrackName index of the CTTT table.  With the search key set to 
  574. 'MexiConc1993' (the foreign key field in CTAY of the record that first matched 
  575. 'Mexican'), the Code+TrackName index for CTTT is searched.  The first key 
  576. starting with 'MexiConc1993' is returned, and its data record.  In that record 
  577. is the track name, track number, and track time.  When done with that record, 
  578. the index can be tranversed in-order (forward, or even backward), and, so long 
  579. as the first 12 characters of the Code+TrackName key match 'MexiConc1993', that 
  580. key's record is used.  When the match is no longer true in those first 12 
  581. characters, which in the example data occurs after 13 tracks have been read, it 
  582. means that all matching keys in that index file have been found, and there are 
  583. no others matching the criterion. 
  584.  
  585. The TrackName part of Code+TrackName (the part of the key after the first 12 
  586. characters) is not needed as a match criterion in this case; TrackName is being 
  587. used solely for the purpose of making the key unique to that particular CD 
  588. Title (all Code fields are the same for each trackname on the CD). 
  589.  
  590. A possible additional index file would be a key based on Code, for CTAY (there 
  591. is such an index already for CTTT).  This would allow indexed access to the 
  592. CTAY table when looking for the Title of a track name.  (In other words, you 
  593. have a list of track names of all CDs in the database, in track name order, and 
  594. want to know the CD Title for each track you see.)  Even without an index this 
  595. can be done by using the Code value in CTTT as a sequential search lookup value 
  596. in CTAY (searching for the matching Code value in CTAY).  This additional index 
  597. is not used here. 
  598.  
  599.  
  600. ΓòÉΓòÉΓòÉ 6.4. Tutorial: Creating the Data Files ΓòÉΓòÉΓòÉ
  601.  
  602. Now that the output requirements are known, and the layout of the data records 
  603. of the two data files constructed, and the index access methods designed, the 
  604. database can be created.  Bullet provides routines to create the files of the 
  605. database according to specifications that you supply. 
  606.  
  607. The CTAY (Code-Title-Artist-Year) and CTTT (Code-Track-TrackName-Time) tables 
  608. are to be in this format: 
  609.  
  610.   CTAY TABLE
  611.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  612.  Γöé   CODE     Γöé      TITLE      Γöé     ARTIST      ΓöéYEAR Γöé
  613.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  614.   MexiConc1993  Mexican Moon      Concrete Blonde  1993   (sample record)
  615.      :
  616.  
  617.  CODE      character data, 12 bytes
  618.  TITLE     character data, 32 bytes
  619.  ARTIST    character data, 35 bytes
  620.  YEAR      character data, 4 bytes
  621.  
  622.  
  623.   CTTT TABLE
  624.  ΓöîΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö¼ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÉ
  625.  Γöé    CODE    ΓöéTRKΓöé     TRACKNAME      ΓöéTIME Γöé
  626.  ΓööΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓöÇΓö┤ΓöÇΓöÇΓöÇΓöÇΓöÇΓöÿ
  627.   MexiConc1993  01 Jenny I Read         05:18   (sample record)
  628.       :
  629.  
  630.  CODE      character data, 12 bytes
  631.  TRK       character data, 2 bytes
  632.  TRACKNAME character data, 40 bytes
  633.  TIME      character data, 5 bytes
  634.  
  635. The fields are sized primarily on expected need.  Since each DBF record has a 
  636. 1-byte tag field, the sum of the above record layouts, including the tag byte, 
  637. is aligned to an even 4-byte size.  An admirable goal, but not a primary design 
  638. consideration.  CTAY is 84 bytes per record; CTTT is 60 bytes per record. 
  639.  
  640. Data is not entered during the create process.  That comes later.  The create 
  641. is only to make the physical files.  The following is the Bullet code required 
  642. to build the two data files.  The index files are covered later. 
  643.  
  644. typedef struct _CTAY {
  645.  CHAR tag;
  646.  CHAR code[12];
  647.  CHAR title[32];
  648.  CHAR artist[35];
  649.  CHAR year[4];
  650. } CTAY;         // (total CTAY record length is 84 bytes)
  651. CTAY ctayRec;
  652.  
  653. CHAR ctayName[] = "CTAY.DBF";
  654. ULONG ctayID=0;                             // handle of CTAY file
  655. FIELDDESCTYPE ctayFieldList[4];             // 4 fields used by the record
  656. memset(ctayFieldList,0,sizeof(ctayFieldList));  // init unused bytes to 0
  657.  
  658. typedef struct _CTTT {
  659.  CHAR tag;
  660.  CHAR code[12];
  661.  CHAR trk[2];
  662.  CHAR trackName[40];
  663.  CHAR time[5];
  664. } CTTT;         // (total CTTT record length is 60 bytes)
  665. CTTT ctttRec;
  666.  
  667. CHAR ctttName[] = "CTTT.DBF";
  668. ULONG ctttID=0;
  669. FIELDDESCTYPE ctttFieldList[4];
  670. memset(ctttFieldList,0,sizeof(ctttFieldList));
  671.  
  672. // field descriptor info for CTAY
  673.  
  674. strcpy(ctayFieldList[0].fieldName, "CODE");
  675. ctayFieldList[0].fieldType = 'C';
  676. ctayFieldList[0].fieldLen = 12;
  677. ctayFieldList[0].fieldDC = 0;
  678.  
  679. strcpy(ctayFieldList[1].fieldName, "TITLE");
  680. ctayFieldList[1].fieldType = 'C';
  681. ctayFieldList[1].fieldLen = 32;
  682. ctayFieldList[1].fieldDC = 0;
  683.  
  684. strcpy(ctayFieldList[2].fieldName, "ARTIST");
  685. ctayFieldList[2].fieldType = 'C';
  686. ctayFieldList[2].fieldLen = 35;
  687. ctayFieldList[2].fieldDC = 0;
  688.  
  689. strcpy(ctayFieldList[3].fieldName, "YEAR");
  690. ctayFieldList[3].fieldType = 'C';
  691. ctayFieldList[3].fieldLen = 4;
  692. ctayFieldList[3].fieldDC = 0;
  693.  
  694. // field descriptor info for CTTT
  695.  
  696. strcpy(ctttFieldList[0].fieldName, "CODE");
  697. ctttFieldList[0].fieldType = 'C';
  698. ctttFieldList[0].fieldLen = 12;
  699. ctttFieldList[0].fieldDC = 0;
  700.  
  701. strcpy(ctttFieldList[1].fieldName, "TRACK");
  702. ctttFieldList[1].fieldType = 'C';
  703. ctttFieldList[1].fieldLen = 2;
  704. ctttFieldList[1].fieldDC = 0;
  705.  
  706. strcpy(ctttFieldList[2].fieldName, "TRACKNAME");
  707. ctttFieldList[2].fieldType = 'C';
  708. ctttFieldList[2].fieldLen = 40;
  709. ctttFieldList[2].fieldDC = 0;
  710.  
  711. strcpy(ctttFieldList[3].fieldName, "TIME");
  712. ctttFieldList[3].fieldType = 'C';
  713. ctttFieldList[3].fieldLen = 5;
  714. ctttFieldList[3].fieldDC = 0;
  715.  
  716. // create the CTAY file
  717.  
  718. CDP.func = CREATE_DATA_XB;
  719. CDP.filenamePtr = ctayName;
  720. CDP.noFields = 4;
  721. CDP.fieldListPtr = ctayFieldList;
  722. CDP.fileID = 3;
  723. rez = BULLET(&CDP);
  724. if (rez) {
  725.    printf("Failed CTAY create.  Err: %d\n",rez);
  726.    return(rez);
  727. }
  728.  
  729. // create the CTTT file
  730.  
  731. CDP.func = CREATE_DATA_XB;
  732. CDP.filenamePtr = ctttName;
  733. CDP.noFields = 4;
  734. CDP.fieldListPtr = ctttFieldList;
  735. CDP.fileID = 3;
  736. rez = BULLET(&CDP);
  737. if (rez) {
  738.    printf("Failed CTTT create.  Err: %d\n",rez);
  739.    return(rez);
  740. }
  741.  
  742.  
  743. ΓòÉΓòÉΓòÉ 6.5. Tutorial: Opening the Data Files ΓòÉΓòÉΓòÉ
  744.  
  745. Before using a data file it must be opened.  Any DBF file can be opened, 
  746. whether created by Bullet or another program.  Before creating indexes for the 
  747. data files created here, the data files must be open.  The handles of the open 
  748. data files are used in the index file create process. 
  749.  
  750.  
  751. // open CTAY and store handle to ctayID
  752.  
  753. OP.func = OPEN_DATA_XB;
  754. OP.filenamePtr = ctayData;
  755. OP.asMode = READWRITE | DENYNONE;
  756. rez = BULLET(&OP);
  757. if (rez) {
  758.    printf("Failed CTAY file open.  Err: %d\n",rez);
  759.    return(rez);
  760. }
  761. ctayID = OP.handle;
  762.  
  763. // open CTTT and store handle to ctttID
  764.  
  765. OP.func = OPEN_DATA_XB;
  766. OP.filenamePtr = ctttData;
  767. OP.asMode = READWRITE | DENYNONE;
  768. rez = BULLET(&OP);
  769. if (rez) {
  770.    printf("Failed CTTT file open.  Err: %d\n",rez);
  771.    return(rez);
  772. }
  773. ctttID = OP.handle;
  774.  
  775.  
  776. ΓòÉΓòÉΓòÉ 6.6. Tutorial: Creating the Index Files ΓòÉΓòÉΓòÉ
  777.  
  778. Two pairs of index files are used.  For CTAY, Title+Artist and Artist+Title; 
  779. for CTTT, Code+TrackName and TrackName+Code.  These are expected to be unique, 
  780. and so the index files are specified to not accept duplicate keys.  Also, 
  781. rather than using the full field sizes for key expressions, substrings are 
  782. specified.  Long keys affect performance, both in index file size and general 
  783. access speed (smaller is usually better), and using the entire field data does 
  784. little to differentiate the key (for the uniqueness requirement).  If 
  785. DUPS_ALLOWED were specified, even shorter keys could be used, though duplicates 
  786. generally are not desirable.  If there comes a record whose generated key is 
  787. not unique (i.e., it already belongs to another already-added record), either 
  788. modify the data entered so that its key is different, if possible, or redo your 
  789. index files to allow duplicates.  You could also play if 'safe' and permit 
  790. duplicates keys to occur from the outset, knowing that not many duplicates will 
  791. occur, where if they do, you can continue and let Bullet managed the duplicate 
  792. key with an enumerator.  If many duplicates of keys are possible, re-evaluate 
  793. your key expression to make it more unique.  This is done by using a compound 
  794. key with more field components.  Still, the fewer components in a key, and the 
  795. shorter, the better the key is. 
  796.  
  797. Index file creation: 
  798.  
  799. CHAR xTitleName[] = "TITLE.IX3";
  800. CHAR xTitleExp[] = "SUBSTR(TITLE,1,8)+SUBSTR(ARTIST,1,8)";
  801. CHAT xTitleBuffer[16];          // key buffer for later use
  802.                                 // note that if DUPS_ALLOWED, the key buffer must
  803.                                 // provide room for the enumerator (2 bytes more)
  804.  
  805. CHAR xArtistName[] = "ARTIST.IX3";
  806. CHAR xArtistExp[] = "SUBSTR(ARTIST,1,8)+SUBSTR(TITLE,1,8)";
  807. CHAT xArtistBuffer[16];
  808.  
  809. CHAR xCodeName[] = "CODETRK.IX3";
  810. CHAR xCodeExp[] = "CODE+SUBSTR(TRACKNAME,1,12)";
  811. CHAT xCodeBuffer[24];
  812.  
  813. CHAR xTrackName[] = "TRKNAME.IX3";
  814. CHAR xTrackExp[] = "SUBSTR(TRACKNAME,1,12)+CODE";
  815. CHAT xTrackBuffer[24];
  816.  
  817. // create two index files for CTAY
  818.  
  819. CIP.func = CREATE_INDEX_XB;
  820. CIP.filenamePtr = xTitleName;
  821. CIP.keyExpPtr = xTitleExp;
  822. CIP.xbLink = ctayID;            // the handle of the open CTAY file
  823. CIP.sortFunction = NLS_SORT;    // sort key by NLS for proper mixed-case order
  824. CIP.codePage = 0;               // use OS-default code page
  825. CIP.countryCode = 0;            // use OS-default country code
  826. CIP.collatePtr = NULL;          // no need for a special collate table
  827. CIP.nodeSize = 512;             // 512-byte node size (or 1024, 2048 bytes)
  828. rez = BULLET(&CIP);
  829. if (rez) {
  830.    printf("Failed Title index create.  Err: %d\n",rez);
  831.    return(rez);
  832. }
  833.  
  834. CIP.filenamePtr = xArtistName;
  835. CIP.keyExpPtr = xArtistExp;     // other values still valid from above
  836. rez = BULLET(&CIP);
  837. if (rez) {
  838.    printf("Failed Artist index create.  Err: %d\n",rez);
  839.    return(rez);
  840. }
  841.  
  842. // create two index files for CTTT
  843.  
  844. CIP.func = CREATE_INDEX_XB;
  845. CIP.filenamePtr = xCodeName;
  846. CIP.keyExpPtr = xCodeExp;
  847. CIP.xbLink = ctttID;            // as above...
  848. CIP.sortFunction = NLS_SORT;
  849. CIP.codePage = 0;
  850. CIP.countryCode = 0;
  851. CIP.collatePtr = NULL;
  852. CIP.nodeSize = 512;
  853. rez = BULLET(&CIP);
  854. if (rez) {
  855.    printf("Failed Code index create.  Err: %d\n",rez);
  856.    return(rez);
  857. }
  858.  
  859. CIP.filenamePtr = xTrackName;
  860. CIP.keyExpPtr = xTrackExp;      // other values still valid from above
  861. rez = BULLET(&CIP);
  862. if (rez) {
  863.    printf("Failed TrackName index create.  Err: %d\n",rez);
  864.    return(rez);
  865. }
  866.  
  867.  
  868. ΓòÉΓòÉΓòÉ 6.7. Tutorial: Opening the Index Files ΓòÉΓòÉΓòÉ
  869.  
  870. Before using an index file it must be opened.  Only Bullet index files can be 
  871. opened. 
  872.  
  873. // open Title index and store handle to xTitleID
  874.  
  875. OP.func = OPEN_INDEX_XB;
  876. OP.filenamePtr = xTitleName;
  877. OP.asMode = READWRITE | DENYNONE;
  878. OP.xbLink = ctayID;                     // note xbLink
  879. rez = BULLET(&OP);
  880. if (rez) {
  881.    printf("Failed Title index open.  Err: %d\n",rez);
  882.    return(rez);
  883. }
  884. xTitleID = OP.handle;
  885.  
  886. // open Artist index and store handle to artistID
  887.  
  888. OP.func = OPEN_INDEX_XB;
  889. OP.filenamePtr = xArtistName;
  890. OP.asMode = READWRITE | DENYNONE;
  891. OP.xbLink = ctayID;
  892. rez = BULLET(&OP);
  893. if (rez) {
  894.    printf("Failed Artist index open.  Err: %d\n",rez);
  895.    return(rez);
  896. }
  897. xArtistID = OP.handle;
  898.  
  899. // open Code index and store handle to xCodeID
  900.  
  901. OP.func = OPEN_INDEX_XB;
  902. OP.filenamePtr = xCodeName;
  903. OP.asMode = READWRITE | DENYNONE;
  904. OP.xbLink = ctttID;
  905. rez = BULLET(&OP);
  906. if (rez) {
  907.    printf("Failed Code index open.  Err: %d\n",rez);
  908.    return(rez);
  909. }
  910. xCodeID = OP.handle;
  911.  
  912. // open TrackName index and store handle to xTrackNameID
  913.  
  914. OP.func = OPEN_INDEX_XB;
  915. OP.filenamePtr = xTrackName;
  916. OP.asMode = READWRITE | DENYNONE;
  917. OP.xbLink = ctttID;
  918. rez = BULLET(&OP);
  919. if (rez) {
  920.    printf("Failed TrackName index open.  Err: %d\n",rez);
  921.    return(rez);
  922. }
  923. xTrackNameID = OP.handle;
  924.  
  925.  
  926. ΓòÉΓòÉΓòÉ 6.8. Tutorial: Inserting CD Title Data ΓòÉΓòÉΓòÉ
  927.  
  928. The files have been created, and are open.  Data may now inserted into the 
  929. database.  The term 'inserted' is used in contrast to 'added' since Bullet 
  930. 'adds' data only, while it 'inserts' data and key information together (and 
  931. especially, the key is inserted, in order).  The CD data entry would typically 
  932. be done via the keyboard.  This tutorial assumes that this has already been 
  933. done, and that the data items are in the following structure variables: 
  934. ctayRec for CD title data; ctttRec for track data. 
  935.  
  936. First, the CD title record is added to CTAY with a key inserted into the Title 
  937. index and another key into Artist index.  Data entered by the user consists of 
  938. CD title, artist, and year.  The Code field is generated by the program code, 
  939. shown below. 
  940.  
  941. // ctayRec has CD title, artist, and year -- generate Code field data
  942.  
  943. strncpy(ctayRec.code  ,ctayRec.title,4);   // first 4 of title
  944. strncpy(ctayRec.code+4,ctayRec.artist,4);  // first 4 of artist
  945. strncpy(ctayRec.code+8,ctayRec.year,4);    // and 4 of year make the Code field
  946.  
  947. // insert CD title data (one data record added, two index files inserted into)
  948.  
  949. AP[0].func = INSERT_XB;
  950. AP[0].handle = xTitleID;        // handle of Title index
  951. AP[0].recNo = 0;                // required
  952. AP[0].recPtr = &ctayRec;        // the CD title record
  953. AP[0].keyPtr = xTitleBuffer;    // key buffer
  954. AP[0].nextPtr = &AP[1];         // since two index files, point to next
  955. AP[1].handle = xArtistID:       // handle of Artist index
  956. AP[1].recNo = 0x80000000;       // required
  957. AP[1].recPtr = &ctayRec;        // the CD title record
  958. AP[1].keyPtr = xArtistBuffer;   // key buffer
  959. AP[1].nextPtr = NULL;
  960.  
  961. rez = BULLET(&AP[0]);
  962. if (rez) {                      // rez is not error, but pack index of error
  963.    rc = AP[abs(rez)-1].stat;
  964.    printf("Insert failed, pack: %d, err: %d\n",rez,rc);
  965.    return(rc);
  966. }
  967.  
  968. A CD title has been entered.  That's the first part of the data entry.  Next, 
  969. each track on that CD needs to be entered.  It needs the Code field data 
  970. generated above, along with the general track data (track name, etc.). 
  971.  
  972.  
  973. ΓòÉΓòÉΓòÉ 6.9. Tutorial: Inserting CD Track Data ΓòÉΓòÉΓòÉ
  974.  
  975. During the CD title insert, a Code field value was generated.  That field value 
  976. is used for each of the track entries inserted into database for this CD.  The 
  977. actual track data has already been placed in the ctttRec structure variable (by 
  978. the main program code, not shown here), and only the Code field of ctttRec 
  979. needs to be set.  Once done, the track record is inserted, this time into the 
  980. CTTT data file and the Code and Track index files. 
  981.  
  982. //
  983. // this code section is repeated for each track on the CD
  984. //
  985.  
  986. // copy Code field data from CTAY
  987.  
  988. strncpy(ctttRec.code,ctayRec.code,12); // use Title's Code for each Track entry
  989.  
  990. // insert track data (one data record added, two index files inserted into)
  991.  
  992. AP[0].func = INSERT_XB;
  993. AP[0].handle = xCodeID;         // handle of Code index
  994. AP[0].recNo = 0;                // required
  995. AP[0].recPtr = &ctttRec;        // the track record
  996. AP[0].keyPtr = xCodeBuffer;     // key buffer
  997. AP[0].nextPtr = &AP[1];         // since two index files, point to next
  998. AP[1].handle = xTrackID:        // handle of TrackName index
  999. AP[1].recNo = 0x80000000;       // required
  1000. AP[1].recPtr = &ctttRec;        // the track record
  1001. AP[1].keyPtr = xTrackBuffer;    // key buffer
  1002. AP[1].nextPtr = NULL;
  1003.  
  1004. rez = BULLET(&AP[0]);
  1005. if (rez) {                      // rez is not error, but pack index of error
  1006.    rc = AP[abs(rez)-1].stat;
  1007.    printf("Insert failed, pack: %d, err: %d\n",rez,rc);
  1008.    return(rc);
  1009. }
  1010.  
  1011. // and repeat for each track on the CD
  1012.  
  1013. The database now contains a complete entry for the one CD.  This process is 
  1014. repeated for each CD that is to entered into the database.  This is the data 
  1015. entry process.  Data retrieval is covered next. 
  1016.  
  1017.  
  1018. ΓòÉΓòÉΓòÉ 6.10. Tutorial: Retrieving Data ΓòÉΓòÉΓòÉ
  1019.  
  1020. The database can be accessed in several different ways.  For indexed access, 
  1021. any index file can be used.  Alternatively, direct access without an index 
  1022. could also be used.  Generally, since there's no guarantee that the physical 
  1023. order of rows in the database is in any order at all, index access is usually 
  1024. desired.  Possible retrievals are by: 
  1025.  
  1026. 1. CD title, in alphabetical order, and, from information from the CD title, 
  1027. all tracks on the CD.  The tracks are read into an array and sorted by track 
  1028. number.  Alternatively, a separate index could be used to order track entries 
  1029. by TrackNo+TrackName(+etc.), but since there are so few tracks per CD 
  1030. (generally less than 20), it's much more efficient to simply get all tracks for 
  1031. a CD title into an array, and then sort that array for presentation. 
  1032. Otherwise, an index file would need to be maintained on a permanent basis, and 
  1033. for something that can easily be done at run-time (and then discarded). 
  1034.  
  1035. 2. Artist, in alpha order.  Access is similar to CD title, above, since it uses 
  1036. the same data file (CTAY).  As above, tracks for each artist's title can then 
  1037. be retrieved.  The only difference between this and the CD title access is that 
  1038. this lists CDs by artist, rather than by title. 
  1039.  
  1040. 3. Track name, in alphabetical order.  This lists all tracks by track name, in 
  1041. order, with different tracks intermixed with CD titles.  In other words, if 
  1042. three CDs had the track called "In the Summer Time", then each of those tracks 
  1043. would appear together, one after the other.  There is no index available in 
  1044. this database to access the CD on which the track name appears, so you cannot 
  1045. go from trackname alone to CD title (by index).  However, since the Code field 
  1046. is available, and is common to each data file, the Code field value of a track 
  1047. record can be used to sequentially search the Title records for a match.  This 
  1048. is a non-indexed search.  Access is slower than if an index were available, but 
  1049. unless you created indexes for all possible search methods, some sequential 
  1050. (read: slow) searching may be required.  For smaller files (less than 10,000 
  1051. records), or where only a few such searches occur, this may be perfectly 
  1052. acceptable. 
  1053.  
  1054. An index on Code exists (for CTTT, but not CTAY), and you may find a use for 
  1055. this other than for use as a foreign key lookup.  Also, you may create ad hoc 
  1056. index files whenever you need to, and these can be deleted when no longer 
  1057. required.  Since Bullet can create an index for even a large file in just a few 
  1058. seconds, this is a viable option; the few seconds needed to create an index may 
  1059. be many times repaid in the time saved in sequential searches on a non-indexed 
  1060. access. 
  1061.  
  1062. The first retrieval mentioned is shown next. 
  1063.  
  1064. // for each CD title in the database, display all its tracks
  1065.  
  1066.                         // ctayRec already defined
  1067. CTTT cttyRecs[59];      // store each Track record for later sorting by track#
  1068.  
  1069. // This would be repeated for each CD title (only the first is shown).
  1070. // Note: For the next CD title, GET_NEXT_XB would be used.  If necessary,
  1071. // the key just accessed could be stored (preserved), then laster reaccessed
  1072. // using GET_EQUAL_XB again, and then immediately followed with a GET_NEXT_XB.
  1073. // This way, you can stop processing completely, and restart up where you left
  1074. // off.
  1075.  
  1076. // files are locked as required (e.g., full-lock, shared)
  1077.  
  1078. AP.func = GET_FIRST_XB;
  1079. AP.handle = xTitleID;
  1080. AP.recPtr = &ctayRec;
  1081. AP.keyPtr = xTitleBuffer;
  1082. rez = BULLET(&AP);
  1083. while (rez==0) {
  1084.    printf("Title: %s  Artist: %s  Year: %s\n",
  1085.            ctayRec.title,
  1086.            ctayRec.artist,
  1087.            ctayRec.year);
  1088.  
  1089.    // get each track belonging to this CD title (same Code values)
  1090.  
  1091.    int trk=0;                            // counter
  1092.    memset(xCodeBuffer,0,sizeof(xCodeBuffer)); // clear it to 0
  1093.    strncpy(xCodeBuffer,ctayRec.code,12); // copy Code to search-for buffer
  1094.  
  1095.    AP.func = GET_EQUAL_XB;
  1096.    AP.handle = xCodeID;
  1097.    AP.recPtr = &ctttRecs[trk];
  1098.    AP.keyPtr = xCodeBuffer;             // find Code
  1099.    rez = BULLET(&AP);
  1100.  
  1101.    // rather than print each when gotten, collect them, sort, then display
  1102.    // if rez==0 here then Code matched exactly, no strncmp needed, otherwise,
  1103.    // there's no match on the first 12 characters of Code
  1104.  
  1105.    AP.func = GET_NEXT_XB;               // continue getting while same Code
  1106.    while (rez==0) {
  1107.       trk++;                            // limit to array size...
  1108.       AP.recPtr = &ctttRecs[trk];       // read into next array record
  1109.       rez = BULLET(&AP);
  1110.       if (rez==0) {
  1111.  
  1112.          // if code field in CTTT no longer the same as CTAY, then have them all
  1113.  
  1114.          if (strncmp(ctttRecs[trk].code,ctayRec.code,12)!=0) {
  1115.             rez = 1;
  1116.             break;                      // different Code fields
  1117.          }
  1118.       }
  1119.    }
  1120.  
  1121.    // if rez==1 or at end of file then no error, sort and display --
  1122.    // trk at this point is number of tracks that matched Code (1-based)
  1123.    // DoSortOf... routine sorts the ctttRecs array with trk count of elements
  1124.  
  1125.    if ((rez==1) | (rez==EXB_END_OF_FILE)) {
  1126.       DoSortOfTheTrackRecordsByTrackNumber(&ctttRecs[0],trk);
  1127.  
  1128.       // print each track record, now sorted by track number
  1129.  
  1130.       for (i=0;i < trk;i++) {
  1131.          printf("Trk: %s  Name: %s   Time: %s\n",
  1132.                  ctttRecs[i].trk,
  1133.                  ctttRecs[i].trackName,
  1134.                  ctttRecs[i].time);
  1135.       }
  1136.    else {
  1137.        printf("failed, rez: %d\n",rez);
  1138.        return(rez);
  1139.    }
  1140. }
  1141.  
  1142.  
  1143. ΓòÉΓòÉΓòÉ 6.11. Tutorial: Preparing to End Your Program ΓòÉΓòÉΓòÉ
  1144.  
  1145. It's proper programming practice to perform an orderly shutdown of Bullet when 
  1146. ending your program.  This also extends to files, too, where even if you are 
  1147. not ending your program, but are finished using a file, close that file so that 
  1148. you release the resources allocated for it. 
  1149.  
  1150. In the event that an abnormal termination occurs, and you are unable to release 
  1151. outstanding locks and close all files, you may choose to call EXIT_XB and allow 
  1152. that to close files (the OS releases locks when the file is closed).  If you 
  1153. are unable to call even EXIT_XB, there is still another method that gets 
  1154. Bullet's attention.  During Bullet initialization, the EXIT_XB routine is 
  1155. registered with the OS so that whenever your program terminates (or is 
  1156. terminated), EXIT_XB is called automatically.  This ensures that headers are 
  1157. properly written in all but the most severe of abnormal terminations (abend), 
  1158. such as a lockup. 
  1159.  
  1160. // all outstanding locks should have been released immediately after use
  1161.  
  1162. // close each file that was opened
  1163.  
  1164. HP.func = CLOSE_DATA_XB
  1165. HP.handle = xTitleID;
  1166. if (HP.handle) rez = BULLET(&HP);
  1167. if (rez) printf("close failed, err: %d\n",rez);
  1168.  
  1169. HP.handle = xArtistID;
  1170. if (HP.handle) rez = BULLET(&HP);
  1171. if (rez) printf("close failed, err: %d\n",rez);
  1172.  
  1173. HP.handle = xCodeID;
  1174. if (HP.handle) rez = BULLET(&HP);
  1175. if (rez) printf("close failed, err: %d\n",rez);
  1176.  
  1177. HP.handle = xTrackID;
  1178. if (HP.handle) rez = BULLET(&HP);
  1179. if (rez) printf("close failed, err: %d\n",rez);
  1180.  
  1181. EP.func = EXIT_XB;
  1182. rez = BULLET(&EP);
  1183. if (rez) printf("exit failed, err: %d\n",rez);
  1184.  
  1185. // Bullet is now deinitialized, and must be INIT_XB'ed before further use
  1186.  
  1187.  
  1188. ΓòÉΓòÉΓòÉ 7. History of Changes ΓòÉΓòÉΓòÉ
  1189.  
  1190. Changes Made 
  1191.  
  1192. 2.050 26-Feb-96: 
  1193.  
  1194.    1. Shareware refresh released. 
  1195.  
  1196.  2.044 31-Jan-96: 
  1197.  
  1198.    1. Fixed DUPS_ALLOWED bug at INSERT_XB where error EXB_TOP_OF_FILE or error 
  1199.       EXB_TOO_MANY_DUPLICATES would be returned. 
  1200.  
  1201.  2.043  3-Jan-96: 
  1202.  
  1203.    1. Added atomic key access for NEXT_KEY, PREV_KEY, GET_NEXT, and GET_PREV 
  1204.       for simpler use in multi-threaded programs. 
  1205.    2. Changed EXB_SHARED_LOCK_ON in BULLET2.H (was ERR_ rather than EXB_). 
  1206.  
  1207.  2.042 20-Dec-95: 
  1208.  
  1209.    1. MAKE_DIR_DOS was expecting directory name in DFP.bufferPtr.  Changed to 
  1210.       expect path in DFP.filenamePtr. 
  1211.  
  1212.  2.040 28-Oct-95: 
  1213.  
  1214.    1. BACKUP_FILE_XB extended to back up related memo file on DBF backup. 
  1215.    2. [2.033] Fixed memo file problems. 
  1216.    3. [2.032] Win95 version available. 
  1217.    4. [2.031] DOSX32 version available. 
  1218.  
  1219.  2.031 11-Sep-95: 
  1220.  
  1221.    1. Added DP.fieldOffset to documentation for GET_DESCRIPTOR_XB. 
  1222.    2. Instance tracker purified of DosEnterCritSec need. 
  1223.  
  1224.  2.030 9-Sep-95: 
  1225.  
  1226.    1. Removed erroneous '...header reload...' in online docs of RELOCK_DATA_XB. 
  1227.    2. Default maximum filesizes set to 2047 MB from 2048 MB (absolute max is 
  1228.       4095 MB). 
  1229.    3. Fixed REINDEX_XB so that it actually uses re-evaluted key expression. 
  1230.    4. ATEXIT_XB is obsolete. 
  1231.    5. BREAK_XB is obsolete. 
  1232.  
  1233.  2.020 31-Aug-95: 
  1234.  
  1235.    1. Locality and other cache-related options can be set at file open. 
  1236.    2. IP.versionBullet changed to *1000 from *100 (2020 is version 2.020). 
  1237.    3. Instance tracker corrected. 
  1238.  
  1239.  2.01  22-Aug-95: 
  1240.  
  1241.    1. Changed index header to 1024 bytes from 768 for sector-alignment. 
  1242.    2. Changed header ID to '31ch' from '30ch'. 
  1243.  
  1244.  2.00  20-Aug-95: 
  1245.  
  1246.  Preliminary release. 
  1247.  
  1248.  
  1249. ΓòÉΓòÉΓòÉ 8. Bullet Include File ΓòÉΓòÉΓòÉ
  1250.  
  1251. The Bullet/2 C/C++ header file, BULLET2.H: 
  1252.  
  1253.  
  1254. /* BULLET2.H    3-Jan-96-chh
  1255.  *
  1256.  *  Bullet/2 header for 32-bit C/C++
  1257.  *  Bullet call numbers, parameter packs, and error number equates
  1258.  *
  1259.  */
  1260.  
  1261. #ifndef __BULLET_H
  1262. #define __BULLET_H
  1263.  
  1264. /*
  1265.  * The #pragma pack(1)/#pragma pack() is no longer required since all
  1266.  * structure members in this header will align properly -- all are
  1267.  * 32-bit size except for the structure "FieldDescType", but fieldDA
  1268.  * member (a LONG) is at a 32-bit alignment already (at byte offset +12).
  1269.  * The altFieldLength member, same structure, is also already at
  1270.  * proper alignment for a 16-bit value (at byte offset +18).  If, for
  1271.  * some reason, your compiler aligns the members differently, then you
  1272.  * must use the appropriate compiler pragma to prevent this -- the
  1273.  * FieldDescType size is 32 bytes exactly.  It is not likely that any
  1274.  * conforming compiler will alter this structure, but, now you know what
  1275.  * to do if it does.
  1276.  *
  1277.  * #pragma pack(1)
  1278.  *
  1279.  * NOTE: In your program source code, when you layout your record buffer
  1280.  * structure, you must use the #pragma pack(1)/#pragma pack() directives
  1281.  * around it since it will be, most likely, modified.  The reason is that
  1282.  * this structure MUST start with the implicit TAG field (a BYTE), and so,
  1283.  * unless you use only BYTE/CHAR members in your structure (Bullet can use
  1284.  * binary field values), or take special care to align the record layout
  1285.  * so no padding is performed by the compiler, then you will need to use
  1286.  * the pack(1) pragma.
  1287.  *
  1288.  * #pragma pack()
  1289.  */
  1290.  
  1291. /* the following are assumed defined in OS2DEF.H
  1292.  *
  1293.  * #define VOID void
  1294.  * #define SHORT short
  1295.  * #define LONG long
  1296.  * #define CHAR char
  1297.  *
  1298.  * typedef unsigned char BYTE;
  1299.  * typedef unsigned short USHORT;
  1300.  * typedef unsigned long ULONG;
  1301.  * typedef unsigned char *PSZ;
  1302.  * typedef VOID *PVOID;
  1303.  *
  1304.  * typedef unsigned long APIRET;
  1305.  * #define APIENTRY _System (right-to-left, caller cleans stack, etc.)
  1306.  *
  1307.  * Note: Some compilers may name "_System" differently, like __syscall...
  1308.  *       ...it won't make a difference so long as APIENTRY equates to this
  1309.  */
  1310.  
  1311. #ifdef __cplusplus
  1312.    extern "C" {
  1313. #endif
  1314.  
  1315. LONG APIENTRY BULLET(PVOID datapack);
  1316.  
  1317. // Bullet can return negative result code so use LONG rather than APIRET
  1318.  
  1319. #ifdef __cplusplus
  1320.    }
  1321. #endif
  1322.  
  1323. /* All Bullet routines are mutex-semaphore protected except the following:
  1324.  *
  1325.  * MEMORY_XB            STAT_HANDLE_XB          GET_ERROR_CLASS_XB
  1326.  * QUERY_SYSVARS_XB     CHECK_REMOTE_XB
  1327.  * STAT_DATA_XB         STAT_INDEX_XB
  1328.  *
  1329.  * This means that any thread can call the above routines at any time.  All
  1330.  * other calls in the current process block until the previous thread exits
  1331.  * BULLET.  The default mutex wait is 0 milliseconds, and can be set via
  1332.  * SET_SYSVARS_XB using the MUTEX_SEM_TIMEOUT index.  In the case of
  1333.  * STAT_DATA_XB and STAT_INDEX_XB, these should be used only when there
  1334.  * is no chance that another thread may close that file handle while the
  1335.  * routine is working.
  1336.  *
  1337.  */
  1338.  
  1339.  
  1340.  
  1341. /* ************************************************************************
  1342.  *
  1343.  * xxx.func call numbers
  1344.  *
  1345.  * ************************************************************************/
  1346.  
  1347. #define GEN_ERR_XB              0
  1348. #define INIT_XB                 1  /* system */
  1349. #define EXIT_XB                 2
  1350. #define MEMORY_XB               4
  1351. #define BACKUP_FILE_XB          6
  1352. #define STAT_HANDLE_XB          7
  1353. #define GET_ERROR_CLASS_XB      8
  1354.  
  1355. #define QUERY_SYSVARS_XB        10 /* advanced system */
  1356. #define SET_SYSVARS_XB          11
  1357.  
  1358. #define CREATE_DATA_XB          20 /* data control mid-level */
  1359. #define OPEN_DATA_XB            21
  1360. #define CLOSE_DATA_XB           22
  1361. #define STAT_DATA_XB            23
  1362. #define READ_DATA_HEADER_XB     24
  1363. #define FLUSH_DATA_HEADER_XB    25
  1364. #define COPY_DATA_HEADER_XB     26
  1365. #define ZAP_DATA_HEADER_XB      27
  1366.  
  1367. #define CREATE_INDEX_XB         30 /* key control mid-level */
  1368. #define OPEN_INDEX_XB           31
  1369. #define CLOSE_INDEX_XB          32
  1370. #define STAT_INDEX_XB           33
  1371. #define READ_INDEX_HEADER_XB    34
  1372. #define FLUSH_INDEX_HEADER_XB   35
  1373. #define COPY_INDEX_HEADER_XB    36
  1374. #define ZAP_INDEX_HEADER_XB     37
  1375.  
  1376. #define GET_DESCRIPTOR_XB       40 /* data access mid-level */
  1377. #define GET_RECORD_XB           41
  1378. #define ADD_RECORD_XB           42
  1379. #define UPDATE_RECORD_XB        43
  1380. #define DELETE_RECORD_XB        44
  1381. #define UNDELETE_RECORD_XB      45
  1382. #define PACK_RECORDS_XB         46
  1383. #define DEBUMP_RECORD_XB        47
  1384.  
  1385. #define GET_MEMO_SIZE_XB        50 /* memo access mid-level */
  1386. #define GET_MEMO_XB             51
  1387. #define ADD_MEMO_XB             52
  1388. #define UPDATE_MEMO_XB          53
  1389. #define DELETE_MEMO_XB          54
  1390. #define MEMO_BYPASS_XB          59 /* see below for bypass ordinals */
  1391.  
  1392. #define BYPASS_CREATE_MEMO       1 /* The bypass routines are automatically */
  1393. #define BYPASS_OPEN_MEMO         2 /* performed by BULLET but can be done */
  1394. #define BYPASS_CLOSE_MEMO        3 /* manually, if needed - these numbers are */
  1395. #define BYPASS_READ_MEMO_HEADER  4 /* put in MDP.memoBypass, with MDP.func */
  1396. #define BYPASS_FLUSH_MEMO_HEADER 5 /* set to MEMO_BYPASS_XB */
  1397.  
  1398. #define FIRST_KEY_XB            60 /* key access mid-level */
  1399. #define EQUAL_KEY_XB            61
  1400. #define NEXT_KEY_XB             62
  1401. #define PREV_KEY_XB             63
  1402. #define LAST_KEY_XB             64
  1403. #define STORE_KEY_XB            65
  1404. #define DELETE_KEY_XB           66
  1405. #define BUILD_KEY_XB            67
  1406. #define GET_CURRENT_KEY_XB      68
  1407. #define GET_KEY_FOR_RECORD_XB   69
  1408.  
  1409. #define GET_FIRST_XB            70 /* key and data access high-level */
  1410. #define GET_EQUAL_XB            71
  1411. #define GET_NEXT_XB             72
  1412. #define GET_PREV_XB             73
  1413. #define GET_LAST_XB             74
  1414. #define INSERT_XB               75
  1415. #define UPDATE_XB               76
  1416. #define REINDEX_XB              77
  1417.  
  1418. #define LOCK_XB                 80 /* network control */
  1419. #define UNLOCK_XB               81
  1420. #define LOCK_INDEX_XB           82
  1421. #define UNLOCK_INDEX_XB         83
  1422. #define LOCK_DATA_XB            84
  1423. #define UNLOCK_DATA_XB          85
  1424. #define CHECK_REMOTE_XB         86
  1425. #define RELOCK_XB               87
  1426. #define RELOCK_INDEX_XB         88
  1427. #define RELOCK_DATA_XB          89
  1428.  
  1429. #define DELETE_FILE_DOS         90 /* DOS file I/O low-level */
  1430. #define RENAME_FILE_DOS         91
  1431. #define CREATE_FILE_DOS         92
  1432. #define OPEN_FILE_DOS           93
  1433. #define SEEK_FILE_DOS           94
  1434. #define READ_FILE_DOS           95
  1435. #define WRITE_FILE_DOS          96
  1436. #define CLOSE_FILE_DOS          97
  1437. #define ACCESS_FILE_DOS         98
  1438. #define EXPAND_FILE_DOS         99
  1439. #define MAKE_DIR_DOS            100
  1440. #define COMMIT_FILE_DOS         101
  1441.  
  1442. /* ************************************************************************
  1443.  *
  1444.  * operating system file I/O equates
  1445.  *
  1446.  * ************************************************************************/
  1447.  
  1448. #define READONLY        0x00000000 /* std file access mode */
  1449. #define WRITEONLY       0x00000001 /* no underscore used for std equates */
  1450. #define READWRITE       0x00000002
  1451.  
  1452. #define DENYREADWRITE   0x00000010 /* std file share mode, cannot be 0 */
  1453. #define DENYWRITE       0x00000020
  1454. #define DENYREAD        0x00000030
  1455. #define DENYNONE        0x00000040
  1456. #define NOINHERIT       0x00000080
  1457.  
  1458. #define NO_LOCALITY     0x00000000 /* optional cache modes */
  1459. #define SEQ_LOCALITY    0x00010000
  1460. #define RND_LOCALITY    0x00020000
  1461. #define MIX_LOCALITY    0x00030000
  1462. #define SKIP_CACHE      0x00100000 /* not inherited by child process */
  1463. #define WRITE_THROUGH   0x00400000 /* not inherited by child process */
  1464.  
  1465.  
  1466. #define LOCK_SHARED      1         /* for LP.xlMode and LP.dlMode */
  1467. #define LOCK_EXCLUSIVE   0
  1468.  
  1469. /* ************************************************************************
  1470.  *
  1471.  * .sortFunction IDs, Query/Set item IDs
  1472.  *
  1473.  * ************************************************************************/
  1474.  
  1475. #define CTRYCODE 0      /* signifies default country code (at index create) */
  1476. #define CODEPAGE 0      /* signifies default code page (at index create) */
  1477.  
  1478. #define DUPS_ALLOWED (1 << 16) /* allow duplicate keys (.sortFunction flag) */
  1479.  
  1480. /* All Bullet system vars set to default values at INIT_XB */
  1481. /* Sorts 1-19 also used as CIP.sortFunction (can be OR'ed with DUPS_ALLOWED) */
  1482. /* Intrinsic sorts (1-6) are read-only (R-O) */
  1483.  
  1484. #define ASCII_SORT 1    /* sort by: ASCII value (R-O) */
  1485. #define NLS_SORT   2    /* NLS (R-O) */
  1486. #define S16_SORT   3    /* 16-bit signed integer (R-O) */
  1487. #define U16_SORT   4    /* 16-bit unsigned integer (R-O) */
  1488. #define S32_SORT   5    /* 32-bit signed integer (R-O) */
  1489. #define U32_SORT   6    /* 32-bit unsigned integer (R-O) */
  1490.  
  1491. /* sorts 7 to 9 are reserved */
  1492. /* Custom sort-compare functions are from 10 to 19 */
  1493.  
  1494. #define BUILD_KEY_FUNC  20      /* key build function ptr */
  1495. #define PARSER_FUNC     21      /* key expression parser function ptr */
  1496.  
  1497. #define MUTEX_SEM_HANDLE     29 /* handle of Bullet's mutex semaphore (R-O) */
  1498. #define LOCK_TIMEOUT         30 /* lock-wait timeout (default=0, no wait)*/
  1499. #define MUTEX_SEM_TIMEOUT    31 /* mutex semaphore-wait timeout (def=0,none) */
  1500. #define PACK_BUFFER_SIZE     32 /* pack buffer size (def=0, min autosize) */
  1501. #define REINDEX_BUFFER_SIZE  33 /* reindex buffer size (def=0, min autosize) */
  1502. #define REINDEX_PACK_PCT     34 /* reindex node pack % (default=100, max) */
  1503. #define TMP_PATH_PTR         35 /* temporary file path ptr (default=NULL) */
  1504. #define REINDEX_SKIP_TAG     36 /* index skip tag select (default=0, none) */
  1505. #define COMMIT_AT_EACH       37 /* commit each insert/update in pack (def=0) */
  1506. #define MEMO_BLOCKSIZE       38 /* memo block size (default=512 bytes) */
  1507. #define MEMO_EXTENSION       39 /* memo filename extension (default='DBT\0') */
  1508. #define MAX_DATAFILE_SIZE    40 /* max data size (default=0x7FEFFFFF=2095MB) */
  1509. #define MAX_INDEXFILE_SIZE   41 /* max index size (default=0x7FEFFFFF=2095MB)*/
  1510. #define ATOMIC_MODE          42 /* bit0=1 atomic next/prev key access (def=0)*/
  1511.  
  1512. /* ************************************************************************
  1513.  *
  1514.  * Parameter pack structures, typedefs
  1515.  *
  1516.  * ************************************************************************/
  1517.  
  1518. /* AP, CP, CDP, etc., are suggested variable names */
  1519.  
  1520. typedef struct _ACCESSPACK {
  1521. ULONG func;
  1522. ULONG stat;
  1523. ULONG handle;         /* I, handle of Bullet file to access */
  1524. LONG  recNo;          /* IO, record number */
  1525. PVOID recPtr;         /* I, programmer's record buffer */
  1526. PVOID keyPtr;         /* I, programmer's key buffer */
  1527. PVOID nextPtr;        /* I, NULL if not xaction, else next AP in list */
  1528. } ACCESSPACK; /* AP */
  1529. typedef ACCESSPACK *PACCESSPACK;
  1530.  
  1531. typedef struct _COPYPACK {
  1532. ULONG func;
  1533. ULONG stat;
  1534. ULONG handle;         /* I, handle of Bullet file to copy */
  1535. PSZ   filenamePtr;    /* I, filename to use (drv+path must exist if used) */
  1536. } COPYPACK; /* CP */
  1537. typedef COPYPACK *PCOPYPACK;
  1538.  
  1539. typedef struct _CREATEDATAPACK {
  1540. ULONG func;
  1541. ULONG stat;
  1542. PSZ   filenamePtr;    /* I, filename to use */
  1543. ULONG noFields;       /* I, 1 to 254 */
  1544. PVOID fieldListPtr;   /* I, descriptor list, 1 per field */
  1545. ULONG fileID;         /* I, 0x03 for standard DBF, 0x8B if memo file also */
  1546. } CREATEDATAPACK; /* CDP */
  1547. typedef CREATEDATAPACK *PCREATEDATAPACK;
  1548.  
  1549. typedef struct _CREATEINDEXPACK {
  1550. ULONG func;
  1551. ULONG stat;
  1552. PSZ   filenamePtr;    /* I, filename to use */
  1553. PSZ   keyExpPtr;      /* I, e.g., "SUBSTR(LNAME,1,4)+SSN" */
  1554. LONG  xbLink;         /* I, opened data file handle this indexes */
  1555. ULONG sortFunction;   /* I, 1-9 system, 10-19 custom */
  1556. ULONG codePage;       /* I, 0=use process default */
  1557. ULONG countryCode;    /* I, 0=use process default */
  1558. PVOID collatePtr;     /* I, NULL=use cc/cp else use passed table for sort */
  1559. ULONG nodeSize;       /* I, 512, 1024, or 2048 */
  1560. } CREATEINDEXPACK; /* CIP */
  1561. typedef CREATEINDEXPACK *PCREATEINDEXPACK;
  1562.  
  1563. typedef struct _FIELDDESCTYPE {
  1564. BYTE  fieldName[11];  /* IO, upper A-Z and _; 1-10 chars, 0-filled, 0-term */
  1565. BYTE  fieldType;      /* IO, C,D,L,N, or M */
  1566. LONG  fieldDA;        /* x, offset within record (run-time storage option) */
  1567. BYTE  fieldLen;       /* IO, C=1-255,D=8,L=1,N=1-19,M=10 */
  1568. BYTE  fieldDC;        /* IO, fieldType=N then 0-15 else 0 */
  1569. USHORT altFieldLength;/* IO, 0 */
  1570. BYTE  filler[12];     /* I, 0 */
  1571. } FIELDDESCTYPE; /* nested in _DESCRIPTORPACK */
  1572. typedef FIELDDESCTYPE *PFIELDDESCTYPE;
  1573.  
  1574. typedef struct _DESCRIPTORPACK {
  1575. ULONG func;
  1576. ULONG stat;
  1577. ULONG handle;         /* I, handle of DBF file */
  1578. ULONG fieldNumber;    /* IO, first field is 1 */
  1579. ULONG fieldOffset;    /* O, offset of field within record (tag=offset 0) */
  1580. FIELDDESCTYPE FD;     /* IO FD.fieldName only, O for rest of FD */
  1581. } DESCRIPTORPACK; /* DP */
  1582. typedef DESCRIPTORPACK *PDESCRIPTORPACK;
  1583.  
  1584. typedef struct _DOSFILEPACK {
  1585. ULONG func;
  1586. ULONG stat;
  1587. PSZ   filenamePtr;    /* I, filename to use */
  1588. ULONG handle;         /* IO, handle of open file */
  1589. ULONG asMode;         /* I, access-sharing mode */
  1590. ULONG bytes;          /* IO, bytes to read, write, length of */
  1591. LONG  seekTo;         /* IO, seek to offset, current offset */
  1592. ULONG method;         /* I, seek method (0=start of file, 1=current, 2=end) */
  1593. PVOID bufferPtr;      /* I, buffer to read into or write from */
  1594. ULONG attr;           /* I, attribute to create file with */
  1595. PSZ   newNamePtr;     /* I, name to use on rename */
  1596. } DOSFILEPACK; /* DFP */
  1597. typedef DOSFILEPACK *PDOSFILEPACK;
  1598.  
  1599. typedef struct _EXITPACK {
  1600. ULONG func;
  1601. ULONG stat;
  1602. } EXITPACK; /* EP */
  1603. typedef EXITPACK *PEXITPACK;
  1604.  
  1605. typedef struct _HANDLEPACK {
  1606. ULONG func;
  1607. ULONG stat;
  1608. ULONG handle;         /* I, handle of Bullet file */
  1609. } HANDLEPACK; /* HP */
  1610. typedef HANDLEPACK *PHANDLEPACK;
  1611.  
  1612. typedef struct _INITPACK {
  1613. ULONG func;
  1614. ULONG stat;
  1615. ULONG JFTsize;        /* I, max opened files (20-1024+) */
  1616. ULONG versionDOS;     /* O, e.g., 230 for 2.30 */
  1617. ULONG versionBullet;  /* O, e.g., 2019 for 2.019 */
  1618. ULONG versionOS;      /* O, e.g., 4=OS/2 32-bit */
  1619. PVOID exitPtr;        /* O, function pointer to EXIT_XB routine */
  1620. } INITPACK; /* IP */
  1621. typedef INITPACK *PINITPACK;
  1622.  
  1623. typedef struct _LOCKPACK {
  1624. ULONG func;
  1625. ULONG stat;
  1626. ULONG handle;         /* I, handle of Bullet file to lock */
  1627. ULONG xlMode;         /* I, index lock mode (0=exclusive, 1=shared) */
  1628. ULONG dlMode;         /* I, data lock mode (0=exclusive, 1=shared) */
  1629. LONG  recStart;       /* I, if data, first record # to lock, or 0 for all */
  1630. ULONG recCount;       /* I, if data and recStart!=0, # records to lock */
  1631. PVOID nextPtr;        /* I, NULL if not xaction, else next LP in list */
  1632. } LOCKPACK; /* LP */
  1633. typedef LOCKPACK *PLOCKPACK;
  1634.  
  1635. typedef struct _MEMODATAPACK {
  1636. ULONG func;
  1637. ULONG stat;
  1638. ULONG dbfHandle;      /* I, handle of DBF file to which this memo file belongs */
  1639. ULONG memoBypass;     /* I, memo bypass function to do, if any */
  1640. PVOID memoPtr;        /* I, ptr to memo record buffer */
  1641. ULONG memoNo;         /* IO, memo record number (aka block number) */
  1642. ULONG memoOffset;     /* I, position within record to start read/update */
  1643. ULONG memoBytes;      /* IO, number of bytes to read/update */
  1644. } MEMODATAPACK; /* MDP */
  1645. typedef MEMODATAPACK *PMEMODATAPACK;
  1646.  
  1647. typedef struct _MEMORYPACK {
  1648. ULONG func;
  1649. ULONG stat;
  1650. ULONG memory;         /* O, not used in OS/2 */
  1651. } MEMORYPACK; /* MP */
  1652. typedef MEMORYPACK *PMEMORYPACK;
  1653.  
  1654. typedef struct _OPENPACK {
  1655. ULONG func;
  1656. ULONG stat;
  1657. ULONG handle;         /* O, handle of file opened */
  1658. PSZ   filenamePtr;    /* I, Bullet file to open */
  1659. ULONG asMode;         /* I, access-sharing-cache mode */
  1660. LONG  xbLink;         /* I, if index open, xbLink=handle of its opened DBF */
  1661. } OPENPACK; /* OP */
  1662. typedef OPENPACK *POPENPACK;
  1663.  
  1664. typedef struct _QUERYSETPACK {
  1665. ULONG func;
  1666. ULONG stat;
  1667. ULONG item;           /* I, Bullet sysvar item to get/set */
  1668. ULONG itemValue;      /* IO, current/new value */
  1669. } QUERYSETPACK; /* QSP */
  1670. typedef QUERYSETPACK *PQUERYSETPACK;
  1671.  
  1672. typedef struct _REMOTEPACK {
  1673. ULONG func;
  1674. ULONG stat;
  1675. ULONG handle;         /* I, handle of file, or if 0, use RP.drive */
  1676. ULONG drive;          /* I, drive (1=A,2=B,3=C,...0=current) to check */
  1677. ULONG isRemote;       /* O, =1 of handle/drive is remote, =0 if local */
  1678. ULONG flags;          /* O, 0 */
  1679. ULONG isShare;        /* O, 1 */
  1680. } REMOTEPACK; /* RP */
  1681. typedef REMOTEPACK *PREMOTEPACK;
  1682.  
  1683. typedef struct _STATDATAPACK {
  1684. ULONG func;
  1685. ULONG stat;
  1686. ULONG handle;         /* I, handle to check */
  1687. ULONG fileType;       /* O, bit0=1 data file */
  1688. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  1689. ULONG progress;       /* O, 0,1-99% pack progress */
  1690. PVOID morePtr;        /* O, 0 */
  1691. ULONG fields;         /* O, fields per record */
  1692. ULONG asMode;         /* O, access-sharing-cache mode */
  1693. PSZ   filenamePtr;    /* O, filename used in open */
  1694. ULONG fileID;         /* O, first byte of DBF file */
  1695. ULONG lastUpdate;     /* O, high word=year,low byte=day, high byte=month */
  1696. ULONG records;        /* O, data records (including "deleted") */
  1697. ULONG recordLength;   /* O, record length */
  1698. ULONG xactionFlag;    /* O, 0 */
  1699. ULONG encryptFlag;    /* O, 0 */
  1700. PVOID herePtr;        /* O, this file's control address */
  1701. ULONG memoHandle;     /* O, handle of open memo file (0 if none) */
  1702. ULONG memoBlockSize;  /* O, memo file block size */
  1703. ULONG memoFlags;      /* O, bit0=1 dirty */
  1704. ULONG memoLastRecord; /* O, last accessed memo record (0 if none) */
  1705. ULONG memoLastSize;   /* O, size of last accessed memo record (in bytes, +8) */
  1706. ULONG lockCount;      /* O, number of full-locks in force */
  1707. } STATDATAPACK; /* SDP */
  1708. typedef STATDATAPACK *PSTATDATAPACK;
  1709.  
  1710. typedef struct _STATHANDLEPACK {
  1711. ULONG func;
  1712. ULONG stat;
  1713. ULONG handle;         /* I, handle to check */
  1714. LONG  ID;             /* O, bit0=1 data file, bit0=1 index file */
  1715. } STATHANDLEPACK; /* SHP */
  1716. typedef STATHANDLEPACK *PSTATHANDLEPACK;
  1717.  
  1718. typedef struct _STATINDEXPACK {
  1719. ULONG func;
  1720. ULONG stat;
  1721. ULONG handle;         /* I, handle to check */
  1722. ULONG fileType;       /* O, bit0=0 index file */
  1723. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  1724. ULONG progress;       /* O, 0,1-99% reindex progress */
  1725. PVOID morePtr;        /* O, 0 */
  1726. ULONG xbLink;         /* O, XB file link handle */
  1727. ULONG asMode;         /* O, access-sharing-cache mode */
  1728. PSZ   filenamePtr;    /* O, pointer to filename used in open */
  1729. ULONG fileID;         /* O, "31ch" */
  1730. PSZ   keyExpPtr;      /* O, pointer to key expression */
  1731. ULONG keys;           /* O, keys in file */
  1732. ULONG keyLength;      /* O, key length */
  1733. ULONG keyRecNo;       /* O, record number of current key */
  1734. PVOID keyPtr;         /* O, ptr to current key value (valid to keyLength) */
  1735. PVOID herePtr;        /* O, this file's control address */
  1736. ULONG codePage;       /* O, code page at create time */
  1737. ULONG countryCode;    /* O, country code at create time */
  1738. PVOID CTptr;          /* O, collate table ptr, NULL=no collate table present */
  1739. ULONG nodeSize;       /* O, node size */
  1740. ULONG sortFunction;   /* O, sort function ID */
  1741. ULONG lockCount;      /* O, number of full-locks in force */
  1742. } STATINDEXPACK; /* SIP */
  1743. typedef STATINDEXPACK *PSTATINDEXPACK;
  1744.  
  1745. typedef struct _XERRORPACK {
  1746. ULONG func;
  1747. ULONG stat;           /* I, error to check */
  1748. ULONG errClass;       /* O, class of error */
  1749. ULONG action;         /* O, action recommended for error */
  1750. ULONG location;       /* O, location of error */
  1751. } XERRORPACK; /* XEP */
  1752. typedef XERRORPACK *PXERRORPACK;
  1753.  
  1754.  
  1755. /* ************************************************************************
  1756.  *
  1757.  * Error codes
  1758.  *
  1759.  * ************************************************************************/
  1760.  
  1761. #define EXB_NOT_ENOUGH_MEMORY   8  /* cannot get memory requested */
  1762. #define EXB_UNEXPECTED_EOF      38 /* unexpect EOF (bytes read != bytes asked) */
  1763. #define EXB_DISK_FULL           39 /* disk full on WriteFile */
  1764. #define EXB_FILE_EXISTS         80 /* cannot create file since it already exists */
  1765.  
  1766. /* Other operating system errors are as returned by OS itself */
  1767.  
  1768. /* System/general error codes */
  1769.  
  1770. #define EXB_OR_WITH_FAULTS      8192 /* 8192+1 to +4, close-type errors */
  1771. #define EXB_ILLEGAL_CMD         8300 /* function not allowed */
  1772. #define EXB_OLD_DOS             8301 /* OS version < MIN_DOS_NEEDED */
  1773. #define EXB_NOT_INITIALIZED     8302 /* init not active, must do INIT_XB */
  1774. #define EXB_ALREADY_INITIALIZED 8303 /* init already active, must do EXIT_XB */
  1775. #define EXB_TOO_MANY_HANDLES    8304 /* more than 1024 opens requested */
  1776. #define EXB_SYSTEM_HANDLE       8305 /* Bullet won't use or close handles 0-2 */
  1777. #define EXB_FILE_NOT_OPEN       8306 /* file not open (not Bullet handle, including xbLink) */
  1778. #define EXB_FILE_IS_DIRTY       8307 /* tried to reload header but current still dirty */
  1779. #define EXB_BAD_FILETYPE        8308 /* tried key op on non-key file, data op on non... */
  1780. #define EXB_TOO_MANY_PACKS      8309 /* too many INSERT,UPDATE,REINDEX,LOCK_XB packs */
  1781. #define EXB_NULL_RECPTR         8310 /* null record pointer passed to Bullet */
  1782. #define EXB_NULL_KEYPTR         8311 /* null key pointer passed to Bullet */
  1783. #define EXB_NULL_MEMOPTR        8312 /* null memo pointer passed to Bullet */
  1784. #define EXB_EXPIRED             8313 /* evaluation time period has expired */
  1785. #define EXB_BAD_INDEX           8314 /* Query/SetSysVars index beyond last one */
  1786. #define EXB_RO_INDEX            8315 /* SetSysVar index item is read-only */
  1787. #define EXB_FILE_BOUNDS         8316 /* file size > 4GB, or > system var sets */
  1788.  
  1789. /* Multi-access error codes */
  1790.  
  1791. #define EXB_BAD_LOCK_MODE       8401 /* lock mode (LP) not valid */
  1792. #define EXB_NOTHING_TO_RELOCK   8402 /* cannot relock without existing full-lock */
  1793. #define EXB_SHARED_LOCK_ON      8403 /* write access needed but lock is shared (flush on backup) */
  1794.  
  1795. /* Index error codes */
  1796.  
  1797. #define EXB_KEY_NOT_FOUND       8501 /* exact match of key not found */
  1798. #define EXB_KEY_EXISTS          8502 /* key exists already and dups not allowed */
  1799. #define EXB_END_OF_FILE         8503 /* already at last index order */
  1800. #define EXB_TOP_OF_FILE         8504 /* already at first index order */
  1801. #define EXB_EMPTY_FILE          8505 /* nothing to do since no keys */
  1802. #define EXB_CANNOT_GET_LAST     8506 /* cannot locate last key */
  1803. #define EXB_BAD_INDEX_STACK     8507 /* index file is corrupt */
  1804. #define EXB_BAD_INDEX_READ0     8508 /* index file is corrupt */
  1805. #define EXB_BAD_INDEX_WRITE0    8509 /* index file is corrupt */
  1806.  
  1807. #define EXB_OLD_INDEX           8521 /* old index, run through ReindexOld to update */
  1808. #define EXB_UNKNOWN_INDEX       8522 /* not a Bullet index file */
  1809. #define EXB_KEY_TOO_LONG        8523 /* keylength > 62 (or 64 if unique), or is 0 */
  1810.  
  1811. #define EXB_PARSER_NULL         8531 /* parser function pointer is NULL */
  1812. #define EXB_BUILDER_NULL        8532 /* build key function pointer is NULL */
  1813. #define EXB_BAD_SORT_FUNC       8533 /* CIP.sortFunction not valid */
  1814. #define EXB_BAD_NODE_SIZE       8534 /* CIP.nodeSize is not 512, 1024, or 2048 */
  1815. #define EXB_FILENAME_TOO_LONG   8535 /* CIP.filenamePtr->pathname > max path length */
  1816.  
  1817. #define EXB_KEYX_NULL           8541 /* expression is effectively NULL */
  1818. #define EXB_KEYX_TOO_LONG       8542 /* CIP.keyExpPtr->expression > 159 */
  1819. #define EXB_KEYX_SYM_TOO_LONG   8543 /* fieldname/funcname in expression > 10 chars */
  1820. #define EXB_KEYX_SYM_UNKNOWN    8544 /* fieldname/funcname in expression unknown */
  1821. #define EXB_KEYX_TOO_MANY_SYMS  8545 /* too many symbols/fields used in expression */
  1822. #define EXB_KEYX_BAD_SUBSTR     8546 /* invalid SUBSTR() operand in expression */
  1823. #define EXB_KEYX_BAD_SUBSTR_SZ  8547 /* SUBSTR() exceeds field's size */
  1824. #define EXB_KEYX_BAD_FORM       8548 /* didn't match expected symbol in expression */
  1825.  
  1826. #define EXB_NO_READS_FOR_RUN    8551 /* unlikely, use different reindex buffer size */
  1827. #define EXB_TOO_MANY_RUNS       8552 /* unlikely, too many runs (64K or more runs) */
  1828. #define EXB_TOO_MANY_RUNS_FOR_BUFFER 8553 /* unlikely, too many runs for run buffer */
  1829. #define EXB_TOO_MANY_DUPLICATES 8554 /* more than 64K "identical" keys */
  1830.  
  1831. #define EXB_INSERT_RECNO_BAD    8561 /* AP.recNo cannot be > 0 if inserting */
  1832. #define EXB_PREV_APPEND_EMPTY   8562 /* no prev append for insert yet AP.recNo==80000000h */
  1833. #define EXB_PREV_APPEND_MISMATCH 8563 /* prev append's xbLink does not match this */
  1834. #define EXB_INSERT_KBO_FAILED   8564 /* could not back out key at INSERT_XB */
  1835. #define EXB_INSERT_DBO_FAILED   8565 /* could not back out data records at INSERT_XB */
  1836.  
  1837. #define WRN_NOTHING_TO_UPDATE   8571 /* all AP.recNo=0 at UPDATE_XB */
  1838. #define EXB_INTERNAL_UPDATE     8572 /* internal error UPDATE_XB, not in hdl/rec# list */
  1839.  
  1840. #define EXB_FAILED_DATA_RESTORE 8573 /* could not restore original data record (*) */
  1841. #define EXB_FAILED_KEY_DELETE   8574 /* could not remove new key (*) */
  1842. #define EXB_FAILED_KEY_RESTORE  8575 /* could not restore original key(*) */
  1843. /* *original error, which forced a back-out, has been replaced by this error */
  1844. /* this error is always returned in the first AP.stat (-1 on data, 1 on index) */
  1845.  
  1846. /* Data error codes */
  1847.  
  1848. #define EXB_EXT_XBLINK          8601 /* xbLink handle is not internal DBF (is -1) */
  1849. #define EXB_FIELDNAME_TOO_LONG  8602 /* fieldname is > 10 characters */
  1850. #define EXB_RECORD_TOO_LONG     8603 /* record length is > 64K */
  1851. #define EXB_FIELD_NOT_FOUND     8604 /* fieldname not found in descriptor info */
  1852. #define EXB_BAD_FIELD_COUNT     8605 /* fields <= 0 or >= MAX_FIELDS (Init,Open) */
  1853.                                      /* and also GetDescriptor by field number */
  1854. #define EXB_BAD_HEADER          8606 /* bad header (reclen=0, etc., from LocateTo, Flush) */
  1855. #define EXB_BUFFER_TOO_SMALL    8607 /* buffer too small (pack buffer < reclen in pack) */
  1856. #define EXB_INTERNAL_PACK       8608 /* internal error in PackRecords */
  1857. #define EXB_BAD_RECNO           8609 /* record number=0 or > records in data file hdr */
  1858.                                      /* or Pack on empty data file */
  1859. #define WRN_RECORD_TAGGED       8610 /* record's tag field matches skip tag */
  1860.  
  1861. /* Memo error codes */
  1862.  
  1863. #define WRN_CANNOT_OPEN_MEMO    8701 /* DBF says memo file but memo open fails */
  1864. #define EXB_MEMO_NOT_OPEN       8702 /* no open memo file for operation */
  1865. #define EXB_BAD_BLOCKSIZE       8703 /* memo blocksize must be at least 24 bytes */
  1866. #define EXB_MEMO_DELETED        8704 /* memo is deleted */
  1867. #define EXB_MEMO_PAST_END       8705 /* memo data requested is past end of record */
  1868. #define EXB_BAD_MEMONO          8706 /* memo number is not valid */
  1869. #define EXB_MEMO_IN_USE         8707 /* memo add encountered likely corrupt memo file */
  1870. #define EXB_BAD_AVAIL_LINK      8708 /* memo avail link cannot be valid (is 0) */
  1871. #define EXB_MEMO_ZERO_SIZE      8709 /* memo data has no size */
  1872. #define EXB_MEMO_IS_SMALLER     8710 /* memo attempt to shrink but already <= size */
  1873.  
  1874. #endif /* ifndef __BULLET_H */
  1875.  
  1876.  
  1877. ΓòÉΓòÉΓòÉ 9. Bullet Functions ΓòÉΓòÉΓòÉ
  1878.  
  1879. System level                  Advanced system-level 
  1880.  
  1881.  INIT_XB                      QUERY_SYSVARS_XB 
  1882.  EXIT_XB                      SET_SYSVARS_XB 
  1883.  MEMORY_XB 
  1884.  BACKUP_FILE_XB 
  1885.  STAT_HANDLE_XB 
  1886.  GET_ERROR_CLASS_XB 
  1887.  
  1888.  Data low-level               Data mid-level                Memo mid-level 
  1889.  
  1890.  CREATE_DATA_XB               GET_DESCRIPTOR_XB             GET_MEMO_SIZE_XB 
  1891.  OPEN_DATA_XB                 GET_RECORD_XB                 GET_MEMO_XB 
  1892.  CLOSE_DATA_XB                ADD_RECORD_XB                 ADD_MEMO_XB 
  1893.  STAT_DATA_XB                 UPDATE_RECORD_XB              UPDATE_MEMO_XB 
  1894.  READ_DATA_HEADER_XB          DELETE_RECORD_XB              DELETE_MEMO_XB 
  1895.  FLUSH_DATA_HEADER_XB         UNDELETE_RECORD_XB            MEMO_BYPASS_XB 
  1896.  COPY_DATA_HEADER_XB          PACK_RECORDS_XB 
  1897.  ZAP_DATA_HEADER_XB           DEBUMP_RECORD_XB 
  1898.  
  1899.  Index low-level              Index mid-level               Index high-level 
  1900.  
  1901.  CREATE_INDEX_XB              FIRST_KEY_XB                  GET_FIRST_XB 
  1902.  OPEN_INDEX_XB                EQUAL_KEY_XB                  GET_EQUAL_XB 
  1903.  CLOSE_INDEX                  NEXT_KEY_XB                   GET_NEXT_XB 
  1904.  STAT_INDEX_XB                PREV_KEY_XB                   GET_PREV_XB 
  1905.  READ_INDEX_HEADER_XB         LAST_KEY_XB                   GET_LAST_XB 
  1906.  FLUSH_INDEX_HEADER_XB        STORE_KEY_XB                  INSERT_XB 
  1907.  COPY_INDEX_HEADER_XB         DELETE_KEY_XB                 UPDATE_XB 
  1908.  ZAP_INDEX_HEADER_XB          BUILD_KEY_XB                  REINDEX_XB 
  1909.                               GET_CURRENT_KEY_XB 
  1910.                               GET_KEY_FOR_RECORD_XB 
  1911.  
  1912.  Network level                CP level 
  1913.  
  1914.  LOCK_XB                      DELETE_FILE_DOS 
  1915.  UNLOCK_XB                    RENAME_FILE_DOS 
  1916.  LOCK_INDEX_XB                CREATE_FILE_DOS 
  1917.  UNLOCK_INDEX_XB              OPEN_FILE_DOS 
  1918.  LOCK_DATA_XB                 SEEK_FILE_DOS 
  1919.  UNLOCK_DATA_XB               READ_FILE_DOS 
  1920.  CHECK_REMOTE_XB              WRITE_FILE_DOS 
  1921.  RELOCK_XB                    CLOSE_FILE_DOS 
  1922.  RELOCK_INDEX_XB              ACCESS_FILE_DOS 
  1923.  RELOCK_DATA_XB               EXPAND_FILE_DOS 
  1924.                               MAKE_DIR_DOS 
  1925.                               COMMIT_FILE_DOS 
  1926.  
  1927.  
  1928. ΓòÉΓòÉΓòÉ 9.1. INIT_XB ΓòÉΓòÉΓòÉ
  1929.  
  1930. Pack: INITPACK                 Source Example 
  1931.  
  1932.      IN               OUT
  1933.    IP.func          IP.stat
  1934.    IP.JFTsize       IP.versionDOS
  1935.                     IP.versionBullet
  1936.                     IP.versionOS
  1937.                     IP.exitPtr
  1938.  
  1939.  This must be the first routine called.  If it has already been called the 
  1940.  system variables are restored to their defaults, and an error is returned. 
  1941.  Otherwise, the entire Bullet system is initialized, and EXIT_XB is registered 
  1942.  with the OS ExitList handler (DosExitList). 
  1943.  
  1944.  For more than the default open files (generally 20), set IP.JFTsize to the 
  1945.  total number of concurrently open files you need.  Depending on your version, 
  1946.  Bullet manages up to 1024 Bullet files per process (total data and index; memo 
  1947.  files are not counted against this total).  Setting this less than 20 does 
  1948.  nothing.  This number is for Bullet files, your files, pipes -- anything using 
  1949.  a handle.  If you need to account for handles that you are managing, you 
  1950.  should add those to IP.JFTsize.  For example, if you need 10 data files, each 
  1951.  with a memo file, and 2 index files per data file, that is 40 total Bullet 
  1952.  files.  If you need to use 15 other handles, for whatever use, add that number 
  1953.  to the 40 Bullet files, for a total setting of 55.  The OS also uses 3 handles 
  1954.  for itself, so, for all these, IP.JFTsize=58 would be the minimum.  You can 
  1955.  set it higher, but unused handles are wasted handles. In addition, if the 
  1956.  current process has fewer total handles available than the number you 
  1957.  specified in IP.JFTsize, Bullet sets the total available handles to IP.JFTsize 
  1958.  (as the absolute number of handles required).  If the current process already 
  1959.  has more total handles than IP.JFTsize, no action is taken. 
  1960.  
  1961.  On return (where no error occurred), the operating system version is in 
  1962.  IP.versionDOS (*100) and the Bullet version (*1000) in IP.versionBullet. 
  1963.  IP.versionOS return is based on the following table: 
  1964.  
  1965.       Bullet Platform   IP.versionOS
  1966.          MS-DOS 16-bit      0
  1967.           Win3x 16-bit      1
  1968.            DOSX 32-bit      3
  1969.            OS/2 32-bit      4
  1970.     WinNT/Win9x 32-bit      5
  1971.  
  1972.  Not all platforms may be currently available 
  1973.  
  1974.  IP.exitPtr returns with the function pointer to the EXIT_XB routine. This 
  1975.  function pointer is redundant unless specifically mentioned as being required 
  1976.  for your platform.  It is not needed in OS/2. 
  1977.  
  1978.  Note:  References under OUT using *AP.keyPtr or similar (note then *) are used 
  1979.  throughout this manual and indicate that Bullet updates the contents at 
  1980.  AP.keyPtr with data (i.e., Bullet filled the buffer). 
  1981.  
  1982.  
  1983. ΓòÉΓòÉΓòÉ 9.2. EXIT_XB ΓòÉΓòÉΓòÉ
  1984.  
  1985. Pack: EXITPACK                 Source Example 
  1986.  
  1987.      IN               OUT
  1988.    EP.func          EP.stat
  1989.  
  1990.  Call EXIT_XB before ending your program to release any remaining resources 
  1991.  back to the OS.  Open files should be closed by using CLOSE_DATA_XB and 
  1992.  CLOSE_INDEX_XB. EXIT_XB closes any Bullet files that are still open. 
  1993.  
  1994.  This routine is registered with the operating system and so is called 
  1995.  automatically when your program terminates. 
  1996.  
  1997.  
  1998. ΓòÉΓòÉΓòÉ 9.3. ATEXIT_XB ΓòÉΓòÉΓòÉ
  1999.  
  2000. This routine is obsolete.  In OS/2, the EXIT_XB shutdown procedure is 
  2001. registered with the operating system.  For those systems that do not offer this 
  2002. feature in the OS, the compiler run-time routine atexit() is used immediately 
  2003. after calling INIT_XB, using IP.exitPtr as the function pointer for atexit(). 
  2004.  
  2005.  
  2006. ΓòÉΓòÉΓòÉ 9.4. MEMORY_XB ΓòÉΓòÉΓòÉ
  2007.  
  2008. Pack: MEMORYPACK               Source Example 
  2009.  
  2010.      IN               OUT
  2011.    MP.func          MP.stat
  2012.                     MP.memory
  2013.  
  2014.  Returns the largest memory block of unused physical memory. 
  2015.  
  2016.  OS/2 uses virtual memory.  Therefore, returning the amount of 'free' memory is 
  2017.  not indicative of anything useful, other than the amount of memory being 
  2018.  unused, or actually, wasted.  Wasted because it is always better for that 
  2019.  memory to be used for something, than for it to 'stand by' just waiting to be 
  2020.  used. 
  2021.  
  2022.  Future versions may return a more useful value. 
  2023.  
  2024.  Note:  This routine is not mutex-protected. 
  2025.  
  2026.  
  2027. ΓòÉΓòÉΓòÉ 9.5. BACKUP_FILE_XB ΓòÉΓòÉΓòÉ
  2028.  
  2029. Pack: COPYPACK                 Source Example 
  2030.  
  2031.      IN               OUT
  2032.    CP.func          CP.stat
  2033.    CP.handle
  2034.    CP.filenamePtr
  2035.  
  2036.  Copy an open BULLET index file or data/memo files.  BULLET repacks and 
  2037.  reindexes files in place, requiring less disk space to perform the function. 
  2038.  This routine allows a file to be safely copied for a possible later restore. 
  2039.  
  2040.  This function is recommended prior to packing a data file with 
  2041.  PACK_RECORDS_XB.  For index files, COPY_INDEX_HEADER_XB is sufficient since 
  2042.  index files are easily recreated so long as you have the data file along with 
  2043.  the index file header. 
  2044.  
  2045.  A full-lock should be in force before copying.  A shared lock may be used. 
  2046.  
  2047.  If CP.handle belongs to a DBF data file, and if a memo file is attached, the 
  2048.  memo file backup name is as CP.filenamePtr, the backup DBF pathname, but the 
  2049.  extension is always set to "._BT".  For example, if CP.handle is for a DBF 
  2050.  that has a DBT memo file attached, then the current state of the DBF file is 
  2051.  copied to CP.filenamePtr, say, "\CURRBACK\ACCT.DBF", and, in this case, the 
  2052.  DBT memo file is copied to "\CURRBACK\ACCT._BT".  The name of the original 
  2053.  DBF/DBT does not matter.  If MEMO_EXTENSION of SET_SYSVARS_XB has changed the 
  2054.  default, then that extension is used on the memo copy, with '_' replacing its 
  2055.  first character. 
  2056.  
  2057.  To prevent the backing up of a DBT memo file when backing up a DBF data file, 
  2058.  set CP.handle = -CP.handle (i.e., negative CP.handle).  This way, the DBT memo 
  2059.  file is not copied.  To backup only a DBT file, close the DBF and copy the DBT 
  2060.  by some other means. 
  2061.  
  2062.  
  2063. ΓòÉΓòÉΓòÉ 9.6. STAT_HANDLE_XB ΓòÉΓòÉΓòÉ
  2064.  
  2065. Pack: STATHANDLEPACK           Source Example 
  2066.  
  2067.      IN               OUT
  2068.    SHP.func         SHP.stat
  2069.    SHP.handle       SHP.ID
  2070.  
  2071.  Get information on a file handle number to determine if it is a BULLET file, 
  2072.  and if so, its type:  index or data. 
  2073.  
  2074.       SHP.ID   File type
  2075.          0     index, IX3  use STAT_INDEX_XB for file stats
  2076.          1     data, DBF   use STAT_DATA_XB for file stats
  2077.         -1     unknown
  2078.  
  2079.  Only bit0 of SHP.ID is significant if not -1.  So, if bit0=0 then the handle 
  2080.  belongs to an index file.  If bit0=1 then it's a data file. 
  2081.  
  2082.  Memo file handles return as unknown.  A DBF file's memo file handle is stored 
  2083.  in the DBF file's data area, and is returned by STAT_DATA_XB in 
  2084.  SDP.memoHandle. 
  2085.  
  2086.  Note:  This routine is not mutex-protected. 
  2087.  
  2088.  
  2089. ΓòÉΓòÉΓòÉ 9.7. GET_ERROR_CLASS_XB ΓòÉΓòÉΓòÉ
  2090.  
  2091. Pack: XERRORPACK               Source Example 
  2092.  
  2093.      IN               OUT
  2094.    XEP.func         XEP.errClass
  2095.    XEP.stat         XEP.action
  2096.                     XEP.location
  2097.  
  2098.  Get the extended error information for the code passed in XEP.stat. This 
  2099.  information includes the error classification, recommended action, and origin 
  2100.  of the error. 
  2101.  
  2102.  Any system error code can be specified, not necessarily the one that last 
  2103.  occurred.  If a return code is not a BULLET code, then it is a system error 
  2104.  code (from the CP, DosXXX routines). 
  2105.  
  2106.  The ERRCLASS, ERRACT, and ERRLOC items below are OS/2 values, names and 
  2107.  descriptions for DosErrClass(). 
  2108.  
  2109.   Error Classification
  2110.  
  2111.     Value   Name                Description
  2112.       1    ERRCLASS_OUTRES     Out of resources
  2113.       2    ERRCLASS_TEMPSIT    Temporary situation
  2114.       3    ERRCLASS_AUTH       Authorization failed
  2115.       4    ERRCLASS_INTRN      Internal error
  2116.       5    ERRCLASS_HRDFAIL    Device hardware failure
  2117.       6    ERRCLASS_SYSFAIL    System failure
  2118.       7    ERRCLASS_APPEAR     Probably application error
  2119.       8    ERRCLASS_NOTFND     Item not located
  2120.       9    ERRCLASS_BADFMT     Bad format for function or data
  2121.      10    ERRCLASS_LOCKED     Resource or data locked
  2122.      11    ERRCLASS_MEDIA      Incorrect media, CRC error
  2123.      12    ERRCLASS_ALREADY    Action already taken or done, or resource already exists
  2124.      13    ERRCLASS_UNK        Unclassified
  2125.      14    ERRCLASS_CANT       Cannot perform requested action
  2126.      15    ERRCLASS_TIME       Timeout
  2127.  
  2128.  
  2129.   Recommended Action
  2130.  
  2131.     Value   Name                Description
  2132.       1    ERRACT_RETRY        Retry immediately
  2133.       2    ERRACT_DLYRET       Delay and retry
  2134.       3    ERRACT_USER         Bad user input - get new values
  2135.       4    ERRACT_ABORT        Terminate in an orderly manner
  2136.       5    ERRACT_PANIC        Terminate immediately
  2137.       6    ERRACT_IGNORE       Ignore error
  2138.       7    ERRACT_INTRET       Retry after user intervention
  2139.  
  2140.  
  2141.   Origin
  2142.  
  2143.     Value   Name                Description
  2144.       1    ERRLOC_UNK          Unknown
  2145.       2    ERRLOC_DISK         Disk
  2146.       3    ERRLOC_NET          Network
  2147.       4    ERRLOC_SERDEV       Serial device
  2148.       5    ERRLOC_MEM          Memory
  2149.  
  2150.  Note:  This routine is not mutex-protected. 
  2151.  
  2152.  
  2153. ΓòÉΓòÉΓòÉ 9.8. QUERY_SYSVARS_XB ΓòÉΓòÉΓòÉ
  2154.  
  2155. Pack: QUERYSETPACK             Source Example 
  2156.  
  2157.      IN               OUT
  2158.    QSP.func         QSP.stat
  2159.    QSP.item         QSP.itemValue
  2160.  
  2161.  Query a BULLET system variable. 
  2162.  
  2163.  To get the function pointers to the sort-compare functions, use: 
  2164.  
  2165.   QSP.item    FuncPtr To
  2166.      1       ASCII sort compare
  2167.      2       NLS sort compare
  2168.      3       16-bit signed integer
  2169.      4       16-bit unsigned integer
  2170.      5       32-bit signed integer
  2171.      6       32-bit unsigned integer
  2172.      7-9     Reserved
  2173.  
  2174.  All intrinsic sort compares (1-6) point to the same function. They cannot be 
  2175.  called except by BULLET itself.  The integer compare routines are based on 
  2176.  Intel byte order.  For Motorola byte order, ASCII sort can be used for 
  2177.  all-positive numbers, otherwise a custom sort-compare should be used. 
  2178.  
  2179.     10-19    Custom sort-compare functions
  2180.  
  2181.  Before creating or opening an index file with a custom sort-compare function 
  2182.  (which is specified during CREATE_INDEX_XB), that function's address must 
  2183.  first be sent to BULLET using SET_SYSVARS_XB. Thereafter, that function must 
  2184.  be available whenever that index file is accessed.  See Custom Sort-Compare 
  2185.  Function for creating custom sort-compare functions. 
  2186.  
  2187.  To get the function pointers to the build key and expression parser routines, 
  2188.  use: 
  2189.  
  2190.   QSP.item    FuncPtr To
  2191.     20       Build key routine
  2192.     21       Key expression parser routine
  2193.     22-28    Reserved
  2194.  
  2195.  Before creating or opening an index file with a custom build key or expression 
  2196.  parser routine (which is specified at any time, but must be used in a 
  2197.  consistent manner), that routine's address must first be sent to BULLET using 
  2198.  SET_SYSVARS_XB.  Thereafter, that routine should be available since it may be 
  2199.  required again.  See Custom Build-Key Routine for creating a custom build-key 
  2200.  routine and Custom Expression Parser Routine for creating a custom key 
  2201.  expression parser. 
  2202.  
  2203.  To get the BULLET system variables' values, use: 
  2204.  
  2205.   QSP.item    Value To
  2206.     29       (read-only) BULLET mutual-exclusion (mutex) semaphore handle
  2207.     30       Lock file region timeout, in milliseconds (default=0)
  2208.     31       Mutex semaphore request timeout, in milliseconds (default=0)
  2209.     32       Pack buffer size, in bytes (default=0: autosize)
  2210.     33       Reindex buffer size, in bytes (default=0: autosize)
  2211.     34       Reindex node pack percentage, 50-100% (default=100)
  2212.     35       Temporary file path pointer (default=NULL, where TMP= used, then .\)
  2213.     36       Reindex tag field character to skip (default=0, no skip)
  2214.     37       Commit each individual file during INSERT/UPDATE_XB (default=0, defer until flush)
  2215.     38       Memo file block size (default=512 bytes; minimum is 24 bytes)
  2216.     39       Memo file extension (default is "DBT\0")
  2217.     40       Max data file size-1 (default=2047MB, absolute max is 4095MB)
  2218.     41       Max index file size-1 (default=2047MB, absolute max is 4095MB)
  2219.     42       Atomic mode (bit0=1 then atomic Next and Prev access, default=0)
  2220.  
  2221.  The timeout values determine if the kernel should wait for a pre-determined 
  2222.  time before returning an error if the resource cannot be obtained.  The lock 
  2223.  timeout specifies how long to wait for a lock to be obtained in case some 
  2224.  other process has a lock on the same resource.  The mutex timeout specifies 
  2225.  how long to wait for access to BULLET in case some other thread in this 
  2226.  process is in BULLET.  Multiple processes can access BULLET at the same time, 
  2227.  but only one thread in each process can be inside BULLET at any one time. 
  2228.  
  2229.  The buffer sizes, when 0, default to a minimum reasonable size.  Performance 
  2230.  is acceptable at these sizes.  For best performance, provide as much real 
  2231.  memory as possible, up to 512KB.  Larger buffers can be used. 
  2232.  
  2233.  The reindex node pack percentage determines how many keys are packed on a 
  2234.  node.  100% forces as many keys as possible, minus 1. 
  2235.  
  2236.  If the temporary file path pointer is NULL (the default), then the TMP= 
  2237.  environment variable is used to locate any temporary files created by BULLET, 
  2238.  or if that is not found, then the current directory is used.  The pointer 
  2239.  supplied, if any, should be to a string containing an existing path (drive 
  2240.  should be included; a trailing '\' is optional, but recommended).  See 
  2241.  REINDEX_XB for size requirements. 
  2242.  
  2243.  The reindex skip tag character, if encountered in the DBF record's tag field 
  2244.  (the first byte of each record), causes the reindex routine to not place that 
  2245.  record's key value into the index file.  Also, BUILD_KEY_XB returns a warning 
  2246.  if the record supplied has a matching tag character. To disable skip tag 
  2247.  processing, set it to 0. 
  2248.  
  2249.  Inserts and Updates, by default, do not commit each file when that pack is 
  2250.  processed.  Instead, it is left to the programmer to issue a FLUSH_XB to 
  2251.  commit.  To force a commit after each pack file is processed, set CommitAtEach 
  2252.  to 1.  This is not one single commit, but a commit for each file in the pack, 
  2253.  after that file has been processed, but before the next file in the pack is. 
  2254.  This will not prevent a roll-back should it be needed. 
  2255.  
  2256.  A memo file can have at most 589,822 blocks.  At the default 512 bytes per 
  2257.  block, that equates to about 288MB.  If you need more memo space, increase the 
  2258.  block size.  The memo extension default is "DBT\0".  Generally, it's a good 
  2259.  idea to leave it at this. 
  2260.  
  2261.  The maximum file sizes are enforced when adding to or reading from DBF files, 
  2262.  and when inserting into or reading from index files.  The default is 2047 MB 
  2263.  (0x7FEFFFFF).  If your file system permits 4GB files, set the values to 4095 
  2264.  MB (0xFFEFFFFF). 
  2265.  
  2266.  The Atomic mode flag determines how key access is handled.  When bit0=0, the 
  2267.  default, the key routines, NEXT_KEY_XB, PREV_KEY_XB, and GET_NEXT_XB, 
  2268.  GET_PREV_XB, use the internal position of the last gotten key as their 
  2269.  starting point.  In multi-threaded code, it's possible that another thread has 
  2270.  since accessed the same file handle and altered the last gotten key.  By 
  2271.  setting bit0=1, key access (next or previous) can now specify a starting point 
  2272.  (typically already set up in AP.keyPtr), rather than starting at the last 
  2273.  accessed key for that handle (which may have been changed by another thread). 
  2274.  
  2275.  Note:  This routine is not mutex-protected. 
  2276.  
  2277.  
  2278. ΓòÉΓòÉΓòÉ 9.9. SET_SYSVARS_XB ΓòÉΓòÉΓòÉ
  2279.  
  2280. Pack: QUERYSETPACK             Source Example 
  2281.  
  2282.      IN               OUT
  2283.    QSP.func         QSP.stat
  2284.    QSP.item         QSP.itemValue
  2285.    QSP.itemValue
  2286.  
  2287.  Set a BULLET system variable, returning the previous value. 
  2288.  
  2289.  To use, set QSP.item to the item to set, and QSP.itemValue with the value to 
  2290.  use (function's address, variable's timeout value, etc., whatever the case may 
  2291.  be).  On return, QSP.itemValue is the previous value that QSP.item was set to. 
  2292.  
  2293.   QSP.item    FuncPtr To
  2294.      1       ASCII sort compare
  2295.      2       NLS sort compare
  2296.      3       16-bit signed integer
  2297.      4       16-bit unsigned integer
  2298.      5       32-bit signed integer
  2299.      6       32-bit unsigned integer
  2300.      7-9     Reserved
  2301.  
  2302.  All intrinsic sort compares (1-6) point to the same function. They cannot be 
  2303.  called except by BULLET itself.  They should not be overloaded with custom 
  2304.  functions.  If you have a custom sort-compare, use one of the custom slots. 
  2305.  The integer compare routines are based on Intel byte order.  For Motorola byte 
  2306.  order, ASCII sort can be used for all-positive numbers, otherwise a custom 
  2307.  sort-compare should be used. 
  2308.  
  2309.     10-19    Custom sort-compare functions
  2310.  
  2311.  Before creating or opening an index file with a custom sort-compare function 
  2312.  (which is specified during CREATE_INDEX_XB), that function's address must 
  2313.  first be sent to BULLET using this routine. Thereafter, that function must be 
  2314.  available whenever that index file is accessed.  See Custom Sort-Compare 
  2315.  Function for creating custom sort-compare functions. 
  2316.  
  2317.  To set the function pointers to the build key and expression parser routines, 
  2318.  use: 
  2319.  
  2320.   QSP.item    FuncPtr To
  2321.     20       Build key routine
  2322.     21       Key expression parser routine
  2323.     22-28    Reserved
  2324.  
  2325.  Before creating or opening an index file with a custom build key or expression 
  2326.  parser routine (which is specified at any time, but must be used in a 
  2327.  consistent manner), that routine's address must first be sent to BULLET using 
  2328.  this routine.  Thereafter, that routine should always be ready (in a callable 
  2329.  state) since it may be required again.  See Custom Build-Key Routine for 
  2330.  creating a custom build-key routine and Custom Expression Parser Routine for 
  2331.  creating a custom key expression parser. 
  2332.  
  2333.  To set the BULLET system variables' values, use: 
  2334.  
  2335.   QSP.item    Value To
  2336.     30       Lock file bytes timeout, in milliseconds (default=0)
  2337.     31       Mutex semaphore request timeout, in milliseconds (default=0)
  2338.     32       Pack buffer size, in bytes (default=0: autosize)
  2339.     33       Reindex buffer size, in bytes (default=0: autosize)
  2340.     34       Reindex node pack percentage, 50-100% (default=100)
  2341.     35       Temporary file path pointer (default=NULL, where TMP= used, then .\)
  2342.     36       Reindex tag field character to skip (default=0, no skip)
  2343.     37       Commit each individual file during INSERT/UPDATE_XB (default=0, defer until flush)
  2344.     38       Memo file block size (default=512 bytes; minimum is 24 bytes)
  2345.     39       Memo file extension (default is "DBT\0")
  2346.     40       Max data file size-1 (default=2047MB, absolute max is 4095MB)
  2347.     41       Max index file size-1 (default=2047MB, absolute max is 4095MB)
  2348.     42       Atomic mode (bit0=1 then atomic Next and Prev access, default=0)
  2349.  
  2350.  The timeout values determine if the kernel should wait for a pre-determined 
  2351.  time before returning an error if the resource cannot be obtained.  The lock 
  2352.  timeout specifies how long to wait for a lock to be obtained in case some 
  2353.  other process has a lock on the same resource.  The mutex timeout specifies 
  2354.  how long to wait for access to BULLET in case some other thread in this 
  2355.  process is in BULLET.  Multiple processes can access BULLET at the same time, 
  2356.  but only one thread in each process can be inside BULLET at any one time. 
  2357.  
  2358.  The buffer sizes, when 0, default to a minimum reasonable size.  Performance 
  2359.  is acceptable at these sizes.  For best performance, provide as much real 
  2360.  memory as possible, up to 512KB.  Larger buffers can be used. 
  2361.  
  2362.  The reindex node pack percentage determines how many keys are packed on a 
  2363.  node.  100% forces as many keys as possible, minus 1. 
  2364.  
  2365.  If the temporary file path pointer is NULL (the default), then the TMP= 
  2366.  environment variable is used to locate any temporary files created by BULLET, 
  2367.  or if that is not found, then the current directory is used.  The pointer 
  2368.  supplied, if any, should be to a string containing an existing path (drive 
  2369.  should be included; a trailing '\' is optional, but recommended).  See 
  2370.  REINDEX_XB for size requirements. 
  2371.  
  2372.  The reindex skip tag character, if encountered in the DBF record's tag field 
  2373.  (the first byte of each record), causes the reindex routine to not place that 
  2374.  record's key value into the index file.  Also, BUILD_KEY_XB returns a warning 
  2375.  if the record supplied has a matching tag character. To disable skip tag 
  2376.  processing, set it to 0. 
  2377.  
  2378.  Inserts and Updates, by default, do not commit each file when that pack is 
  2379.  processed.  Instead, it is left to the programmer to issue a FLUSH_XB to 
  2380.  commit.  To force a commit after each pack file is processed, set CommitAtEach 
  2381.  to 1.  This is not one single commit, but a commit for each file in the pack, 
  2382.  after that file has been processed, but before the next file in the pack is. 
  2383.  This will not prevent a roll-back should it be needed. 
  2384.  
  2385.  A memo file can have at most 589,822 blocks.  At the default 512 bytes per 
  2386.  block, that equates to about 288MB.  If you need more memo space, increase the 
  2387.  block size.  The memo extension default is "DBT\0".  Generally, it's a good 
  2388.  idea to leave it at this. 
  2389.  
  2390.  The maximum file sizes are enforced when adding to or reading from DBF files, 
  2391.  and when inserting into or reading from index files.  The default is 2047 MB 
  2392.  (0x7FEFFFFF).  If your file system permits 4GB files, set the values to 4095 
  2393.  MB (0xFFEFFFFF). 
  2394.  
  2395.  The Atomic mode flag determines how key access is handled.  When bit0=0, the 
  2396.  default, the key routines, NEXT_KEY_XB, PREV_KEY_XB, and GET_NEXT_XB, 
  2397.  GET_PREV_XB, use the internal position of the last gotten key as their 
  2398.  starting point.  In multi-threaded code, it's possible that another thread has 
  2399.  since accessed the same file handle and altered the last gotten key.  By 
  2400.  setting bit0=1, key access (next or previous) can now specify a starting point 
  2401.  (typically already set up in AP.keyPtr), rather than starting at the last 
  2402.  accessed key for that handle (which may have been changed by another thread). 
  2403.  
  2404.  Note:  Issuing INIT_XB restores all system variables (those setable via this 
  2405.  routine) and function pointers to their default values.  This is done even if 
  2406.  INIT_XB returns an error that BULLET has already been initialized. 
  2407.  
  2408.  
  2409. ΓòÉΓòÉΓòÉ 9.10. SET_DVMON_XB ΓòÉΓòÉΓòÉ
  2410.  
  2411. This routine is obsolete. 
  2412.  
  2413.  
  2414. ΓòÉΓòÉΓòÉ 9.11. CREATE_DATA_XB ΓòÉΓòÉΓòÉ
  2415.  
  2416. Pack: CREATEDATAPACK           Source Example 
  2417.  
  2418.      IN               OUT
  2419.    CDP.func         CDP.stat
  2420.    CDP.filenamePtr
  2421.    CDP.noFields
  2422.    CDP.fieldListPtr
  2423.    CDP.fileID
  2424.  
  2425.  Create a new BULLET DBF data file with the name at CDP.filenamePtr, and an 
  2426.  optional DBT memo file. 
  2427.  
  2428.  Before using this routine, allocate an array of field descriptors of type 
  2429.  FIELDDESCTYPE, one for each field in the record (number of fields as set in 
  2430.  CDP.noFields). It is recommended  that this allocation be zeroed before use 
  2431.  since fieldnames and reserved entries must be 0-filled: 
  2432.  
  2433.      FIELDDESCTYPE fieldList[12];  // 12 fields used in data record
  2434.        :
  2435.      memset(fieldList,0,sizeof(fieldList)); // init unused bytes to 0 (required)
  2436.  
  2437.  Filename 
  2438.  
  2439.  The drive and path must exist if used as part of the filename. Long filenames 
  2440.  may be used if supported by the file system in use. As with all text strings 
  2441.  used by Bullet, the filename must end in a '\0'. 
  2442.  
  2443.  Number of Fields 
  2444.  
  2445.  The number of descriptors in the array, described next.  Each field has a 
  2446.  descriptor.  The tag field is not a formal field, and so has no descriptor, 
  2447.  and is not counted in the number of fields.  The maximum fields is 254 
  2448.  according to the DBF standard.  Bullet allows 255, but 254 should be used if 
  2449.  creating a standard DBF file. 
  2450.  
  2451.  Field Descriptors 
  2452.  
  2453.  For each field, a descriptor is used to identify and type it.  These 
  2454.  descriptors are assigned to an array; the pointer to that array is assigned to 
  2455.  CDP.fieldListPtr.  The format of the descriptor follows, with a physical 
  2456.  format in DBF File Format. 
  2457.  
  2458.  Γûá Fieldname 
  2459.  
  2460.  10 characters plus null byte terminator.  Valid fieldname characters are ASCII 
  2461.  A-Z (upper-case) and the underscore (ASCII 95).  All bytes after the fieldname 
  2462.  must be null bytes.  E.g., if the fieldname is "LNAME", five characters, the 
  2463.  following six bytes (including the 11th byte) are set to 0. The eleventh byte 
  2464.  is always a null byte since 10 characters is the maximum fieldname length. 
  2465.  Extended ASCII characters (above 127) should not be used. 
  2466.  
  2467.   fieldList[0].fieldname = "ANYNAME";   // see memset() above
  2468.  
  2469.  Γûá Field type and size 
  2470.  
  2471.  Standard Xbase field types are C, D, L, M, and N: 
  2472.  
  2473.  Type   Description 
  2474.    C    Character field, any code page character, 1 to 255 characters. 
  2475.         Null bytes are not desirable except as a string terminator.  There is 
  2476.         no requirement that strings be terminated with a '\0'.  The field data 
  2477.         should be left-justified within the field, but this is not required (in 
  2478.         which case use leading spaces, not 0 bytes). 
  2479.  
  2480.                        fieldList[0].fieldType = 'C';
  2481.                        fieldList[0].fieldLen = 25;   // since C type, space fill field data
  2482.                        fieldList[0].fieldDC = 0;
  2483.  
  2484.    D    Date field, valid ASCII digits for date, 8 characters. 
  2485.         The physical format is YYYYMMDD, where YYYY is the year (1999), MM is 
  2486.         the month (1-12), and DD the day (1-31).  The date field is always 8 
  2487.         bytes long, and is in ASCII digits ('19991231').  If no date, set to 
  2488.         all spaces. 
  2489.  
  2490.                        fieldList[0].fieldType = 'D';
  2491.                        fieldList[0].fieldLen = 8;
  2492.                        fieldList[0].fieldDC = 0;
  2493.  
  2494.    L    Logical field, <SPACE> Y N T F y n t f, 1 character. 
  2495.         A single-byte field.  When not yet initialized the value will be a 
  2496.         <SPACE> (ASCII 32).  This is typically displayed as a '?' to the user, 
  2497.         indicating that the field has not been initialized.  Initialized values 
  2498.         are variations of yes, no, true, false ('Y', 'y', etc.). 
  2499.  
  2500.                        fieldList[0].fieldType = 'L';
  2501.                        fieldList[0].fieldLen = 1;
  2502.                        fieldList[0].fieldDC = 0;
  2503.  
  2504.    M    Memo field, 10 ASCII digits, 10 characters. 
  2505.         Field data is used as the block number of the corresponding DBT memo 
  2506.         file.  Each block is typically 512 bytes, with the first block (block 
  2507.         #0) used as the memo file header.  If no block is used in the .DBT by 
  2508.         this record, the field is set to <SPACES>.  The first memo block is 
  2509.         stored as "0000000001".  (This description is valid for dBASE IV and 
  2510.         later memo files, as created and used by BULLET.) Some Xbase versions 
  2511.         use field types B and G as variations of memo files.  They are as M, 
  2512.         but contain general data (as in anything), while memo files contain 
  2513.         only text. BULLET supports any type data in its memo files, and you may 
  2514.         use the CDP.fieldType of 'B' or 'G'. 
  2515.  
  2516.         More than one memo field per record is permitted.  For example, you may 
  2517.         need a memo for the printable address, where the address is free-form 
  2518.         rather than in separate fields (i.e., you have both forms), and another 
  2519.         memo for general notes, and yet a third for problem reports, and so on. 
  2520.         All these, and all memos for the rest of the DBF file, are stored in 
  2521.         the same DBT memo file. 
  2522.  
  2523.         Note:  BULLET does not use the fieldType with regard to identifying 
  2524.         memo field type; it is the programmer's responsibility to check the 
  2525.         fieldType and act on it accordingly. 
  2526.  
  2527.                        fieldList[0].fieldType = 'M';
  2528.                        fieldList[0].fieldLen = 10;
  2529.                        fieldList[0].fieldDC = 0;
  2530.  
  2531.    N    Numeric field, ASCII digits, 19 digits maximum (see below). 
  2532.         All standard Xbase data is stored in ASCII form (for universal 
  2533.         exchange).  Numeric fields are to be right-justified, with leading 
  2534.         spaces, and an aligned decimal point, if any (relative this field in 
  2535.         other records).  Do not end the field with a null byte. 
  2536.  
  2537.         The total size of the numeric field is specified in .fieldLen, which 
  2538.         includes any leading sign, the decimal point, and decimal digits to the 
  2539.         right of the decimal point (if any decimal point). The maximum total 
  2540.         size is 19 places.  If a decimal point, then the number of digits to 
  2541.         the right may be from 1 to 15 digits, but must be no more than the 
  2542.         total-2. 
  2543.  
  2544.                    FieldLen.FieldDC    Example
  2545.                            8.2          " 2345.78"
  2546.                            8.2          "12345.78"
  2547.                            8.2          "-2345.78"
  2548.                            8.1          "123456.8"
  2549.                            8.0          "12345678"
  2550.                            5.3          "2.235"
  2551.                            5.4          (not valid)
  2552.  
  2553.                        fieldList[0].fieldType = 'N';
  2554.                        fieldList[0].fieldLen = 8;
  2555.                        fieldList[0].fieldDC = 2;
  2556.  
  2557.  Although not dBASE compatible, you may use binary fields in your data records. 
  2558.  The Xbase standard always has ASCII data in the data fields, even if the field 
  2559.  is numeric.  For example, an 'N' type field of 8.2 (total 
  2560.  length.decimal-count) is stored as an ASCII text string in the data record, 
  2561.  say, a string like " 1100.55".  If you want dBASE compatibility your field 
  2562.  data must also be ASCII.  However, if you can forgo this requirement, you can 
  2563.  use binary values in the fields. 
  2564.  
  2565.  To do this you must specify a field type of 'Y' (actually, anything but an 
  2566.  'N') and, if it is to be used as a key field, also set the sort function to 
  2567.  the appropriate type (S16_SORT, etc.).  The field length 
  2568.  (fieldList[x].fieldLen) for a 'Y' field type is 2 if 16-bit, and 4 if 32-bit. 
  2569.  Also possible is floating-point (with a custom sort-compare function).  A 
  2570.  likely field type marker for this would be 'F'.  Note that both 'Y' and 'F' 
  2571.  are completely non-standard Xbase types, and only your programs will 
  2572.  understand them. 
  2573.  
  2574.  Note:  'B' should not be used as a binary field type marker since dBASE V uses 
  2575.  'B' to signify a binary-data memo file field.  Bullet makes no distinction in 
  2576.  its memo file data; anything can be placed in them.  Typically, your memo 
  2577.  fields are marked as 'M' in Bullet, but could also be 'B' or 'G'. 
  2578.  
  2579.  File ID 
  2580.  
  2581.  Conventional dBASE DBF files have a CDP.fileID=3.  To create a memo file (DBT, 
  2582.  dBASE IV compatible), set CDP.fileID=x8B.  For the DBT to be created, both 
  2583.  bits 3 and 7 (0x88) must be set.  The other bits may be anything, and are not 
  2584.  checked. 
  2585.  
  2586.  In creating your DBF files, specify CDP.fileID=3 to ensure compatibility 
  2587.  across Xbase versions.  If creating a non-standard DBF (e.g., non-standard 
  2588.  field types, extended field lengths, etc.) it's recommended to use 
  2589.  CDP.fileID=0 or CDP.fileID=1.  For a standard DBF file with a memo file (dBASE 
  2590.  IV or later), use CDP.fileID=0x8B (that's a B, as in bee). 
  2591.  
  2592.  Generally, field data is space-filled.  String terminators are allowed in 
  2593.  C-haracter field types, but should not be used in other fields. 
  2594.  
  2595.  Memo File Creation 
  2596.  
  2597.  If bits 3 and 7 are set in CDP.fileID, a memo file is created for the DBF. The 
  2598.  memo filename will be the same as the DBF name except the extension. The memo 
  2599.  file is created after the DBF, with a block size of 512 bytes, and filename 
  2600.  extension of ".DBT".  The default block size and extension can be overridden 
  2601.  (see SET_SYSVARS_XB) prior to calling this routine. 
  2602.  
  2603.  
  2604. ΓòÉΓòÉΓòÉ 9.12. OPEN_DATA_XB ΓòÉΓòÉΓòÉ
  2605.  
  2606. Pack: OPENPACK                 Source Example 
  2607.  
  2608.      IN               OUT
  2609.    OP.func          OP.stat
  2610.    OP.filenamePtr   OP.handle
  2611.    OP.asMode
  2612.  
  2613.  Open an existing DBF data file for use.  For DBF opens, two parameters are 
  2614.  specified:  the filename and the access-sharing mode.  The OP.xbLink parameter 
  2615.  is used only for index opens, and so is not used here. 
  2616.  
  2617.  The OP.asMode has optional cache mode settings.  The caching modes cover 
  2618.  locality, write-through, and skip cache.  Locality is typically mostly random 
  2619.  (RND_LOCALITY), but may be mostly sequential if the data file has been sorted 
  2620.  and the index file recently reindexed and processing is mostly in-order (first 
  2621.  to last, rather than random).  Locality is used to tune the cache.  Also, 
  2622.  normally, data is written to the cache with control returning immediately to 
  2623.  the program before the disk is written (an asynchronous write).  To force the 
  2624.  write to take place before control is returned (a synchronous write), use the 
  2625.  WRITE_THROUGH mode.  To skip the cache completely, use the SKIP_CACHE mode. 
  2626.  This, as all OP.asMode settings, affects this file handle only. 
  2627.  
  2628.  On a successful open, the file handle is returned.  Use this handle for all 
  2629.  further access to this file.  If the DBF was created with a compatible memo 
  2630.  file, it is also opened.  The handle of the memo file is available via 
  2631.  STAT_DATA_XB, but all access to the memo file is made with the handle of the 
  2632.  memo file's master DBF (the handle returned by this routine in OP.handle). 
  2633.  The memo file is opened using the same OP.asMode. 
  2634.  
  2635.  Note:  FoxPro DBF files with Fox memo files (FPT) use an ID of 0xFF.  Bullet 
  2636.  does not support FoxPro memo files, and so opening a FoxPro DBF with a Fox 
  2637.  memo file returns the warning message, WRN_CANNOT_OPEN_MEMO.  The DBF file is 
  2638.  opened, and the warning can be ignored. 
  2639.  
  2640.  Once open, you can get information on the data file by using STAT_DATA_XB. 
  2641.  
  2642.  Each DBF data file opened allocates and commits at least 4K bytes for internal 
  2643.  use: 
  2644.  
  2645.    Number of Fields     Memory
  2646.         1 to 121            4KB
  2647.       122 to 249            8KB
  2648.       250 to 255           12KB
  2649.  This memory is released when you close the file with CLOSE_DATA_XB. or issue 
  2650.  EXIT_XB. 
  2651.  
  2652.  Note:  You must open the data file before you can open or create any of its 
  2653.  index files. 
  2654.  
  2655.  When BULLET creates a DBF, it forces all fieldnames to upper-case (it's a DBF 
  2656.  requirement) and 0-fills them as well.  On data file opens (OPEN_DATA_XB), it 
  2657.  also does this, and so any header copy (COPY_DATA_HEADER_XB) will have 
  2658.  upper-cased fieldnames (the original file is not changed).  To prevent BULLET 
  2659.  from mapping the fieldnames to upper-case (NLS mapping, though fieldnames 
  2660.  should be standard ASCII characters only), set bit31 of OP.asMode to 1 
  2661.  (0x80000042, for example).  This skips the case mapping.  Zero-filling always 
  2662.  takes place, and starts after the first ' \0' byte in the fieldname. 
  2663.  
  2664.  
  2665. ΓòÉΓòÉΓòÉ 9.13. CLOSE_DATA_XB ΓòÉΓòÉΓòÉ
  2666.  
  2667. Pack: HANDLEPACK               Source Example 
  2668.  
  2669.      IN               OUT
  2670.    HP.func          HP.stat
  2671.    HP.handle
  2672.  
  2673.  Close an existing data file. 
  2674.  
  2675.  Closing the file updates the file header and releases the memory used by the 
  2676.  file.  Any associated memo file is closed, too.  Any outstanding locks should 
  2677.  be unlocked before calling this routine. 
  2678.  
  2679.  Note:  Remaining locks belonging to this handle are released by the OS upon 
  2680.  the successful close. 
  2681.  
  2682.  
  2683. ΓòÉΓòÉΓòÉ 9.14. STAT_DATA_XB ΓòÉΓòÉΓòÉ
  2684.  
  2685. Pack: STATDATAPACK             Source Example 
  2686.  
  2687.      IN               OUT
  2688.    SDP.func         SDP.stat         SDP.recordLength
  2689.    SDP.handle       SDP.fileType     SDP.xactionFlag
  2690.                     SDP.flags        SDP.encryptFlag
  2691.                     SDP.progress     SDP.herePtr
  2692.                     SDP.morePtr      SDP.memoHandle
  2693.                     SDP.fields       SDP.memoBlockSize
  2694.                     SDP.asMode       SDP.memoFlags
  2695.                     SDP.filenamePtr  SDP.memoLastRecord
  2696.                     SDP.fileID       SDP.memoLastSize
  2697.                     SDP.lastUpdate   SDP.lockCount
  2698.                     SDP.records
  2699.  
  2700.  Return information BULLET has on the DBF data file specified by SDP.handle. 
  2701.  
  2702.    Item             Description 
  2703.  stat               Return code of operation 
  2704.  fileType           1 for DBF 
  2705.  flags              Bit0=1 if file has changed since last flush (dirty) 
  2706.                     Bit1=1 if the file has its entire region locked (full lock) 
  2707.                     Bit2=1 if the file has a shared lock in use (cannot write 
  2708.                     to it if so) 
  2709.  progress           Percentage of pack operation completed, 1-99, or 0 if done 
  2710.  morePtr            Always 0 
  2711.  fields             Number of fields per record (does not included implicit tag 
  2712.                     field) 
  2713.  asMode             Access-sharing-cache mode as specified at open (excludes 
  2714.                     NoCaseMap bit31) 
  2715.  filenamePtr        Pointer to the filename as used in OPEN_DATA_XB 
  2716.  fileID             ID byte used when the DBF was created (the first byte of 
  2717.                     the file) 
  2718.  lastUpdate         Date of last change (binary: high word=year (1999), low 
  2719.                     byte=day, high byte=month) 
  2720.  records            Number of records in the DBF (includes any delete-tagged 
  2721.                     records) 
  2722.  recordLength       Total length of a data record, including tag field 
  2723.  xactionFlag        Not currently used 
  2724.  encryptFlag        Not currently used 
  2725.  herePtr            Pointer to the internal data control area for this file 
  2726.                     handle 
  2727.  memoHandle         Handle of open memo file (0 if none) 
  2728.  memoBlockSize      Memo file block size (512 is typical, 24 is minimum) 
  2729.  memoFlags          Bit0=1 dirty 
  2730.  memoLastRecord     Last accessed memo record (0 if none; same as 'block 
  2731.                     number') 
  2732.  memoLastSize       Size of last accessed memo record (in bytes, including 8 
  2733.                     bytes overhead) 
  2734.  lockCount          Number of full-locks in force (locked on first, unlocked on 
  2735.                     last) 
  2736.  
  2737.  Typically, your program tracks whether a particular handle belongs to an index 
  2738.  file or data file.  In cases where this is not possible, call the 
  2739.  STAT_HANDLE_XB. routine to determine what file type a handle is. 
  2740.  
  2741.  Note:  In network environments, you should have an exclusive lock on the data 
  2742.  file (and implicitly, therefore, the memo file, if any) before using this 
  2743.  routine to ensure that the information is current.  This also applies to 
  2744.  multi-process environments on a single machine.  This routine is not 
  2745.  mutex-protected.  During the call, the file handle must not be closed by 
  2746.  another thread. 
  2747.  
  2748.  
  2749. ΓòÉΓòÉΓòÉ 9.15. READ_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  2750.  
  2751. Pack: HANDLEPACK               Source Example 
  2752.  
  2753.      IN               OUT
  2754.    HP.func          HP.stat
  2755.    HP.handle
  2756.  
  2757.  Reload the disk copy of the data header for the opened DBF data file handle, 
  2758.  refreshing the in-memory copy.  Any associated memo file is refreshed, too. 
  2759.  
  2760.  Normally, this routine is not called directly but rather is done automatically 
  2761.  when you full-lock the file (LOCK_XB).  This routine does not refresh the 
  2762.  header if the current state is dirty (SDP.flags, bit0=1); it returns an error 
  2763.  if tried. Since it is recommended that a full-lock be in force before using 
  2764.  this routine (shared or exclusive), and since a full-lock always reloads the 
  2765.  header anyway, calling this routine should never be required.  If ever there 
  2766.  is a reason to use this routine without having a full-lock in force, then, of 
  2767.  course, you may need to.  However, it is not wise to reload the header without 
  2768.  a full-lock (which locks the header).  If you are using your own lock 
  2769.  routines, this call will be very useful. 
  2770.  
  2771.  In single-user, single-tasking systems this routine is not needed.  However, 
  2772.  in a multi-user or multi-tasking system it's possible, and desirable, for two 
  2773.  or more programs to use the same data file.  Consider this scenario: A data 
  2774.  file has 100 records.  Two programs access this data file, both opening it. 
  2775.  Program 1 locks the file, adds a new record, then flushes and unlocks the 
  2776.  file.  Program 1 knows that there are now 101 records in the file.  However, 
  2777.  Program 2 is not aware of the changes that Program 1 made--it thinks that 
  2778.  there are still 100 records in the file.  This out-of-sync situation is easily 
  2779.  remedied by having Program 2 reload the data header from the file on disk. 
  2780.  
  2781.  How does Program 2 know that it needs to reload the header? It doesn't. 
  2782.  Instead, BULLET uses a simple, yet effective, approach when dealing with this. 
  2783.  When BULLET full-locks a file, BULLET automatically reloads the header by 
  2784.  using this routine.  When removing the full-lock, BULLET automatically flushes 
  2785.  the header using FLUSH_DATA_HEADER_XB (unless the current lock is a shared 
  2786.  lock (SDP.flags bit2=1)). 
  2787.  
  2788.  
  2789. ΓòÉΓòÉΓòÉ 9.16. FLUSH_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  2790.  
  2791. Pack: HANDLEPACK               Source Example 
  2792.  
  2793.      IN               OUT
  2794.    HP.func          HP.stat
  2795.    HP.handle
  2796.  
  2797.  Write the in-memory copy of the data header for the opened DBF data file 
  2798.  handle to disk.  The actual write occurs only if the header has been changed 
  2799.  (the dirty bit is set).  Any associated memo file is flushed, too.  This 
  2800.  routine ensures that the data header on disk matches exactly the data header 
  2801.  that is being maintained by BULLET. 
  2802.  
  2803.  Normally, this routine is not called directly but rather is done automatically 
  2804.  when you unlock the file (UNLOCK_XB).  This routine does not write out the 
  2805.  header if the current lock state is shared (SDP.flags, bit2=1); it returns an 
  2806.  error if tried.  Unlocking a full-lock performs a flush automatically, and so 
  2807.  you may never need to explicitly call this routine.  Also, when relocking from 
  2808.  an exclusive full-lock to a shared full-lock, an automatic flush is performed. 
  2809.  
  2810.  Assume the following: A data file with 100 records.  Your program opens the 
  2811.  data file and adds 1 record.  Physically, there are 101 records on disk. 
  2812.  However, the header image of the data file on disk still reads 100 records. 
  2813.  This isn't a problem, BULLET uses its internal copy of the data header and the 
  2814.  internal copy does read 101 records.  But, if there were a system failure now, 
  2815.  the image of the header would not get updated since the disk image is written 
  2816.  only on a CLOSE_ or FLUSH_DATA_XB, or on EXIT_XB (and also prior to 
  2817.  PACK_RECORDS_XB).  After the system restarts, BULLET opens the file, reads the 
  2818.  header and thinks that there are 100 records.  You lost a record.  Now, if 
  2819.  after that record add your program issues FLUSH_DATA_HEADER_XB, the header on 
  2820.  disk is refreshed with the in-memory copy, keeping the two in sync.  This 
  2821.  routine also updates the directory entry for the file, keeping things neat 
  2822.  there (file size).  Still, it doesn't come without cost: flushing takes 
  2823.  additional time, therefore, you may elect to flush periodically, or whenever 
  2824.  the system is idle. 
  2825.  
  2826.  Note:  You should have a full-lock on the file before using this routine. 
  2827.  
  2828.  
  2829. ΓòÉΓòÉΓòÉ 9.17. COPY_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  2830.  
  2831. Pack: COPYPACK                 Source Example 
  2832.  
  2833.      IN               OUT
  2834.    CP.func          CP.stat
  2835.    CP.handle
  2836.    CP.filenamePtr
  2837.  
  2838.  Copy the DBF file structure of an open data file to a new file. 
  2839.  
  2840.  This routine makes it easy for you to duplicate the structure of an existing 
  2841.  DBF file without having to specify all the information needed by 
  2842.  CREATE_DATA_XB. The resultant DBF will be exactly like the source, including 
  2843.  number of fields and field descriptions, and an empty memo file, if 
  2844.  applicable. It contains 0 records.  It may be opened as a regular Bullet data 
  2845.  file. 
  2846.  
  2847.  A typical use for this is to create a work file, where only a subset of 
  2848.  records are required.  For example:  You want to process all records of those 
  2849.  whose last name starts with A.  Copy the header to a work file, use GET_XB 
  2850.  routines to get records meeting the criterion, writing those that fit the 
  2851.  criterion to the work file (using either Add/Reindex, or Insert).  A new index 
  2852.  can be specified, or an existing index can be copied using 
  2853.  COPY_INDEX_HEADER_XB. 
  2854.  
  2855.  
  2856. ΓòÉΓòÉΓòÉ 9.18. ZAP_DATA_HEADER_XB ΓòÉΓòÉΓòÉ
  2857.  
  2858. Pack: HANDLEPACK               Source Example 
  2859.  
  2860.      IN               OUT
  2861.    HP.func          HP.stat
  2862.    HP.handle
  2863.  
  2864.  Delete all records in a DBF data file. 
  2865.  
  2866.  This routine is similar to COPY_DATA_HEADER_XB except for one major 
  2867.  difference: All data records in the source file are physically deleted.  No 
  2868.  action is performed on the DBF's memo file, if any. 
  2869.  
  2870.  If you have a DBF file with 100 records and use ZAP_DATA_HEADER_XB on it, all 
  2871.  100 records will be physically deleted and the file truncated as if no records 
  2872.  were ever in the file.  All data records are lost forever. 
  2873.  
  2874.  
  2875. ΓòÉΓòÉΓòÉ 9.19. CREATE_INDEX_XB ΓòÉΓòÉΓòÉ
  2876.  
  2877. Pack: CREATEINDEXPACK          Source Example 
  2878.  
  2879.      IN               OUT
  2880.    CIP.func         CIP.stat
  2881.    CIP.filenamePtr
  2882.    CIP.keyExpPtr
  2883.    CIP.xbLink
  2884.    CIP.sortFunction
  2885.    CIP.codePage
  2886.    CIP.countryCode
  2887.    CIP.collatePtr
  2888.    CIP.nodeSize
  2889.  
  2890.  Create a new BULLET index file. 
  2891.  
  2892.  Before you can create an index file, you must first have opened (and have 
  2893.  created if necessary) the BULLET DBF data file that it is to index. To open 
  2894.  the data file, use OPEN_DATA_XB.  To create the index file, you need to 
  2895.  provide the name to use, the key expression, the DBF file link handle 
  2896.  (obtained from the OPEN_DATA_XB call), sort function/flags, and optionally, 
  2897.  the code page, country code, and collate table.  There's also a node size 
  2898.  parameter.  Select 512, 1024, or 2048 bytes. 
  2899.  
  2900.  Note:  BULLET has an optional external data mode where only indexing is done 
  2901.  -- no data file link is used.  In this mode, BULLET manages the index files of 
  2902.  the key and key data you provide (key data is any 32-bit item, e.g., a record 
  2903.  number, offset, etc.).  This would be useful for indexing non-DBF files, even 
  2904.  files with variable-length records. 
  2905.  
  2906.  Filename 
  2907.  
  2908.  The drive and path must exist if used as part of the filename. Long filenames 
  2909.  may be used if supported by the file system in use. 
  2910.  
  2911.  Key Expression 
  2912.  
  2913.  The key expression is an ASCIIZ string composed of the elements that are to 
  2914.  make up this index file's key.  The key can be composed of any or all of the 
  2915.  fields in the DBF data record, or sub-strings within any of those fields. Up 
  2916.  to 16 component parts can be used in the expression. 
  2917.  
  2918.  Two functions are supported in evaluating a key expression. These are SUBSTR() 
  2919.  and UPPER(): 
  2920.  
  2921.  SUBSTR() extracts part of a field's data starting at a particular position for 
  2922.  x number of characters. 
  2923.  
  2924.  UPPER() converts all lower-case letters to their upper-case equivalent.  Since 
  2925.  BULLET supports NLS, UPPER() conversion is not required for proper sorting of 
  2926.  mixed-case text strings. 
  2927.  
  2928.  Any name used in the key expression must be a valid field name in the DBF data 
  2929.  file.  Below are a few sample key expressions for the given data file 
  2930.  structure: 
  2931.  
  2932.      Name  Type Len DC
  2933.     FNAME    C   25  0
  2934.     LNAME    C   25  0
  2935.     SSN      C    9  0
  2936.     DEPT     N    5  0
  2937.  
  2938.  A few example key expression strings for this structure: 
  2939.  
  2940.     keyExpression[]="LNAME";
  2941.     keyExpression[]="LNAME+FNAME";
  2942.     keyExpression[]="SUBSTR(LNAME,1,4)+SUBSTR(FNAME,1,1)+SUBSTR(SSN,6,4)";
  2943.     keyExpression[]="UPPER(LNAME+FNAME)";  // for ASCII sort function only
  2944.     keyExpression[]="DEPT+SSN";
  2945.  
  2946.  In the last example above, even though DEPT is a numeric field type (N), it 
  2947.  can still be used as a component of a multi-part character key with SSN (whose 
  2948.  type is set to character).  This because numeric fields in dBASE DBF data 
  2949.  files are ASCII digits, not binary values, and are sorted according to the 
  2950.  ASCII value or NLS weight. 
  2951.  
  2952.  The key expression is parsed when the index file is created (this routine) and 
  2953.  also when reindexed (REINDEX_XB.). The parser() function, which parses the key 
  2954.  expression, may be replaced by a programmer-supplied function if additional 
  2955.  functionality is needed.  See Custom Expression Parser Routine for details. 
  2956.  
  2957.  DBF File Link Handle (xbLink) 
  2958.  
  2959.  Since BULLET evaluates the key expression when the file is created (this 
  2960.  routine) or during reindex, it must have access to the DBF file to verify that 
  2961.  the key expression is valid.  You must, therefore, supply the OS file handle 
  2962.  of the opened DBF data file.  If you later change the structure of the DBF 
  2963.  data file (add new fields, remove others, etc.), you must use the reindex 
  2964.  routine to re-evaluation the key expression.  If the key expression is no 
  2965.  longer valid after the data file changes (key field has changed names, etc.), 
  2966.  then you must create a brand new index file with this routine, supplying the 
  2967.  new key expression, rather than reindexing. 
  2968.  
  2969.  Note:  Handles 0-2 are reserved handles and should never be used for any 
  2970.  BULLET routine.  Also, .xbLink of -1 is reserved by BULLET to indicate an 
  2971.  external data index for index create and open routines. 
  2972.  
  2973.  Sort Function 
  2974.  
  2975.  The sort function specifies the sort method for the index file. Essentially, 
  2976.  this defines the compare function used by the access methods employed by 
  2977.  BULLET when doing any type of key access (reading and writing).  There are six 
  2978.  intrinsic sort compare functions available, with an additional 10 sort compare 
  2979.  functions that can be specified by the programmer (see Custom Sort-Compare 
  2980.  Functions). 
  2981.  
  2982.  While not recommended, duplicate key values are supported and managed by 
  2983.  BULLET.  The flag DUPS_ALLOWED is OR'ed with the sort function value to 
  2984.  specify this.  Generally, it is not acceptable to allow duplicate keys for an 
  2985.  index; there should be one key identifying one record without any further 
  2986.  investigation needed to determine if the key is indeed for that record.  This 
  2987.  is not possible, not consistently so, when duplicate keys exist.  It is much 
  2988.  simpler to define your key so that duplicates are not generated, than it is to 
  2989.  deal with duplicate keys once you have them.  If an attempt to insert a key 
  2990.  that already exists in the index file is made, and DUPS_ALLOWED was not 
  2991.  specified when the index file was created, the insert fails (either a 
  2992.  STORE_KEY_XB, an INSERT_XB, or a REINDEX_XB operation), and error 
  2993.  EXB_KEY_EXISTS is returned. 
  2994.  
  2995.  Only data contained within a record should be used to build a key. The 
  2996.  physical record number is not part of the data of a record since it can change 
  2997.  at any time without you knowing about it (during a pack, for example).  Do not 
  2998.  use the record number in an attempt to generate unique keys.  Only use what is 
  2999.  available in the data record itself, so that the key can be built, or rebuilt, 
  3000.  at any time. 
  3001.  
  3002.  The intrinsic sort compare functions of BULLET are: 
  3003.  
  3004.  ASCII_SORT    1 - ASCII  (up to 16 key components) 
  3005.  NLS_SORT      2 - NLS   (up to 16 key components) 
  3006.  S16_SORT      3 - 16-bit signed integer (single component) 
  3007.  U16_SORT      4 - 16-bit unsigned integer (single component) 
  3008.  S32_SORT      5 - 32-bit signed integer (single component) 
  3009.  U32_SORT      6 - 32-bit unsigned integer (single component) 
  3010.  
  3011.  To expand on the basic functionality provided by BULLET, you can supply your 
  3012.  own parser, build, and sort compare routines, and have BULLET use them 
  3013.  instead.  With your own routines in place, you can have BULLET do just about 
  3014.  anything with regard to the index file, including evaluating the key 
  3015.  expression dynamically; using more components; allowing multi-part binary 
  3016.  keys; and more. 
  3017.  
  3018.  Generally, character data (type C) is left-justified, and unused space is 
  3019.  padded with the SPACE character (ASCII 32).  It is permissible to use C-type 
  3020.  strings, or to 0-fill unused space. 
  3021.  
  3022.  Numeric data (type N) is right-justified, with leading space to be padded with 
  3023.  the SPACE character.  It is not permissible to use 0-fill leading bytes 
  3024.  (literal '0' can used, however).  Since the field is right-justified, it is 
  3025.  not generally desirable to terminate the field with a 0 byte, either.  If a 
  3026.  decimal count is specified (not 0),the decimal point location is to be the 
  3027.  same for all entries in this field.  The field description must match the 
  3028.  actual data:  If the field length and field decimal count was specified as 
  3029.  10.2 (10 total bytes, 2 digits to the right of the decimal, then the data is 
  3030.  to be formatted so that '-234567.90' is the longest data that is to be entered 
  3031.  in that field.  All entries in all records for this field must be of the same 
  3032.  format.  For example, " 987654.21", or "   23.01", or "   -1.99" (note the 
  3033.  leading spaces).  Numeric data is indexed as ASCII values (i.e., the key 
  3034.  remains character digits) unless a binary sort function is specified. 
  3035.  
  3036.  Using one of the binary integer sort compare functions requires the following: 
  3037.  
  3038.  1.  Single component expression. 
  3039.  2.  Field type must be N if the field has ASCII digits, or if the data is 
  3040.      binary, then the field type must be Y (actually, anything but N). 
  3041.  3.  If ASCII digits, the value must fit into the function size (-32768 to 
  3042.      32767 or 0-65535 for signed/unsigned 16-bit; 2,147,483,647 to 
  3043.      -2,147,483,648 or 0-4,294,967,295 for 32-bit signed/unsigned values). 
  3044.  
  3045.  Although not dBASE compatible, you may use binary fields in your data records. 
  3046.  The Xbase standard always has ASCII data in the data fields, even if the field 
  3047.  is numeric.  For example, an 'N' type field of 8.2 (total 
  3048.  length.decimal-count) is stored as an ASCII text string in the data record, 
  3049.  say, a string like " 1100.55" (there is no \0 string terminator).  If you want 
  3050.  dBASE compatibility, your field data must be ASCII.  However, if you can forgo 
  3051.  this requirement, you can use binary values in the fields. 
  3052.  
  3053.  To do this you must specify a field type of 'Y' (actually, anything but an 
  3054.  'N') and, if it is to be used as a key field, also set the sort function to 
  3055.  the appropriate type (S16_SORT, etc.).  The field length 
  3056.  (fieldList[x].fieldLen) for a 'Y' field type is 2 if 16-bit, and 4 if 32-bit. 
  3057.  For 64-bit integers, a custom sort-copmare function is required since there is 
  3058.  no intrinsic 64-bit function available. 
  3059.  
  3060.  Note:  'B' should not be used as a binary field type marker since dBASE V uses 
  3061.  'B' to signify a binary-data memo file field.  Bullet makes no distinction in 
  3062.  its memo file data; anything can be place in them.  Typically, your memo 
  3063.  fields are marked as 'M' in Bullet, but could also be 'B' or 'G'. 
  3064.  
  3065.  The key expression string you specify may be up to 159 characters, and 
  3066.  evaluate out to 64 bytes (62 bytes if DUPS_ALLOWED is specified).  The 
  3067.  expression string must be 0-terminated, as are all strings used by BULLET 
  3068.  itself (filenames, etc.). 
  3069.  
  3070.  National Language Support (NLS) 
  3071.  
  3072.  National Language Support is available to properly sort most languages' 
  3073.  alphabets.  BULLET uses NLS to build the collate sequence table (sort table) 
  3074.  that it uses to ensure proper sorting of mixed-case keys as well as the 
  3075.  sorting of foreign language alphabets which use extended-ASCII.  In order for 
  3076.  BULLET to use the proper collate table, it must know what code page and 
  3077.  country code to use.  If not supplied, Bullet gets this information directly 
  3078.  from the OS, which provides the cc/cp for the current process.  If you supply 
  3079.  cc/cp, the code page must be loaded or an error is returned (see OS/2's CHCP 
  3080.  command).  The collate table generated is made part of the index file so that 
  3081.  all subsequent access to the index file maintains the original sort order, 
  3082.  even if, say, the MIS shop is moved to another location/computer system using 
  3083.  another country code/code page.  These three items are discussed below. 
  3084.  
  3085.  Code Page 
  3086.  
  3087.  To use the default code page of the current process, specify a code page of 0. 
  3088.  The OS is queried for the current code page and this code page is then used. 
  3089.  Any valid and available code page can be specified. This is used only if a 
  3090.  custom sort-compare or NLS sort is specified. 
  3091.  
  3092.  Country Code 
  3093.  
  3094.  To use the default country code of the current process, specify a country code 
  3095.  of 0.  The OS is queried for the current country code and this code is then 
  3096.  used.  Any valid country code can be specified.  This is used only if a custom 
  3097.  sort-compare or NLS sort is specified. 
  3098.  
  3099.  Custom Collate Table 
  3100.  
  3101.  If a null-pointer is specified, and a custom sort-compare or NLS sort is 
  3102.  specified, BULLET queries the OS for the collate sequence table to use based 
  3103.  on the code page and country code specified.  Otherwise, the supplied table is 
  3104.  used.  Intrinsic sorts other than NLS use no collate table, and the country 
  3105.  code or code page are not used, either. 
  3106.  
  3107.  To use a sort weight table of your own choosing, supply a non-NULL pointer to 
  3108.  this parameter.  If non-NULL, the passed table is used for sort compares.  The 
  3109.  table is composed of 256 weight values, one per character.  For example, table 
  3110.  position 65 ('A') and table position 97 ('a') could both be weighted 65, so 
  3111.  that that each are considered equal when sorted.  If a custom sort-compare 
  3112.  function was specified, this sort table may, or may not, be used -- it depends 
  3113.  on whether the sort compare function uses the table (it's all up to the custom 
  3114.  sort-compare function's logic). 
  3115.  
  3116.  Typically, you set both the code page and country code = 0, and the collate 
  3117.  table pointer to NULL. 
  3118.  
  3119.  Node Size 
  3120.  
  3121.  The index file is read and written in node-size chunks.  The larger the node 
  3122.  size, the more keys are read or written per chunk.  Generally, a smaller node 
  3123.  size offers better random key access, while a larger node size offers better 
  3124.  sequential key access. 
  3125.  
  3126.  Typically, an average node utilizes 66% of the node space for keys (a very 
  3127.  small number may contain only a few keys, while some may be filled 
  3128.  completely).  In a 512-byte node file, for a key length of 8, there is room 
  3129.  for (512-5)/(keylength+8) nodes, or 31 keys.  Since a typical node is filled 
  3130.  to 66%, that means about 20 keys per node.  For a 2048-byte node file, same 
  3131.  parameters, there is room for (2048-5)/(keylength+8), or 127 keys.  At the 
  3132.  standard 66% load, there are typically 83 keys per 2K node.  That's 3 more 
  3133.  keys per 2K of disk than the 512-byte node gives for 4 nodes (20 keys*4), The 
  3134.  trade-off is that each node is 4 times as large, and so requires 4 times more 
  3135.  searching.  Actual performance differences may be minimal, or may be great. 
  3136.  Run tests on expected data to determine the best for the data and access use. 
  3137.  
  3138.  
  3139. ΓòÉΓòÉΓòÉ 9.20. OPEN_INDEX_XB ΓòÉΓòÉΓòÉ
  3140.  
  3141. Pack: OPENPACK                 Source Example 
  3142.  
  3143.      IN               OUT
  3144.    OP.func          OP.stat
  3145.    OP.filenamePtr   OP.handle
  3146.    OP.asMode
  3147.    OP.xbLink
  3148.  
  3149.  Open an existing index file for use.  For index opens, three parameters are 
  3150.  specified:  the filename, the access-sharing mode, and the handle of the open 
  3151.  DBF file that this file indexes.  It is required to open the data file before 
  3152.  you can open its related index file. 
  3153.  
  3154.  Note:  Handles 0-2 are reserved handles and should never be used for any 
  3155.  BULLET routine.  Also, .xbLink of -1 is reserved by BULLET to indicate an 
  3156.  external data index for index create and open routines. 
  3157.  
  3158.  On a successful open, the file handle is returned.  Use this handle for all 
  3159.  further access to this file. 
  3160.  
  3161.  Once open, you can get information on the index file by using STAT_INDEX_XB. 
  3162.  
  3163.  Each index file that you open allocates and commits 4K bytes for internal use. 
  3164.  This memory is released when you close the file with CLOSE_INDEX_XB or issue 
  3165.  EXIT_XB, or you program terminates. 
  3166.  
  3167.  The OP.asMode has optional cache mode settings.  The caching modes cover 
  3168.  locality, write-through, and skip cache.  Locality is typically mostly random 
  3169.  (RND_LOCALITY), but may be mostly sequential if the data file has been sorted 
  3170.  and the index file recently reindexed and processing is mostly in-order (first 
  3171.  to last, rather than random).  Locality is used to tune the cache.  Also, 
  3172.  normally, data is written to the cache with control returning immediately to 
  3173.  the program before the disk is written (an asynchronous write).  To force the 
  3174.  write to take place before control is returned (a synchronous write), use the 
  3175.  WRITE_THROUGH mode.  To skip the cache completely, use the SKIP_CACHE mode. 
  3176.  This, as all OP.asMode settings, affects this file handle only. 
  3177.  
  3178.  BULLET has an optional external data mode where only indexing is done -- no 
  3179.  data file link is used.  In this mode, BULLET manages the index files of the 
  3180.  key and key data you provide (key data is any 32-bit item, e.g., a record 
  3181.  number, offset, etc.).  This would be useful for indexing non-DBF files, even 
  3182.  files with variable-length records.  Only those routines that do not access 
  3183.  the data file may be used (any routine using AP.recPtr, for example, could not 
  3184.  be used, but NEXT_KEY_XB may). 
  3185.  
  3186.  
  3187. ΓòÉΓòÉΓòÉ 9.21. CLOSE_INDEX_XB ΓòÉΓòÉΓòÉ
  3188.  
  3189. Pack: HANDLEPACK               Source Example 
  3190.  
  3191.      IN               OUT
  3192.    HP.func          HP.stat
  3193.    HP.handle
  3194.  
  3195.  Close an open index file. 
  3196.  
  3197.  Closing the file updates the file header and releases the memory used by the 
  3198.  file.  Any outstanding locks should be unlocked before calling this routine. 
  3199.  
  3200.  Note:  Remaining locks belonging to this handle are released by the OS upon 
  3201.  the successful close. 
  3202.  
  3203.  
  3204. ΓòÉΓòÉΓòÉ 9.22. STAT_INDEX_XB ΓòÉΓòÉΓòÉ
  3205.  
  3206. Pack: STATINDEXPACK            Source Example 
  3207.  
  3208.      IN               OUT
  3209.    SIP.func         SIP.stat         SIP.keyLength
  3210.    SIP.handle       SIP.fileType     SIP.keyRecNo
  3211.                     SIP.flags        SIP.keyPtr
  3212.                     SIP.progress     SIP.herePtr
  3213.                     SIP.morePtr      SIP.codePage
  3214.                     SIP.xbLink       SIP.countryCode
  3215.                     SIP.asMode       SIP.CTptr
  3216.                     SIP.filenamePtr  SIP.nodeSize
  3217.                     SIP.fileID       SIP.sortFunction
  3218.                     SIP.keyExpPtr    SIP.lockCount
  3219.                     SIP.keys
  3220.  
  3221.  Return information BULLET has on the index file specified by SIP.handle. 
  3222.  
  3223.    Item             Description 
  3224.  stat               Return code of operation 
  3225.  fileType           0 for index, IX3 
  3226.  flags              Bit0=1 if file has changed since last flush (dirty) 
  3227.                     Bit1=1 if the file has its entire region locked (full lock) 
  3228.                     Bit2=1 if the file has a shared full-lock in use (cannot 
  3229.                     write to it if so) 
  3230.  progress           Percentage of reindex operation completed, 1-99, or 0 if 
  3231.                     done 
  3232.  morePtr            Always 0 
  3233.  xbLink             handle of the open DBF file this file indexes 
  3234.  asMode             Access-sharing-cache mode as specified at open 
  3235.  filenamePtr        Pointer to the filename as used in OPEN_INDEX_XB 
  3236.  fileID             '31ch' (the first four bytes of the file) 
  3237.  keyExpPtr          Pointer to the key expression used when the index was 
  3238.                     created 
  3239.  keys               Number of keys in the index file 
  3240.  keyLength          Length of the key, including 2-byte enumerator if 
  3241.                     DUPS_ALLOWED 
  3242.  keyRecNo           The DBF record number that the last accessed key indexes 
  3243.  keyPtr             Pointer to the last accessed key (valid for keyLength 
  3244.                     bytes) 
  3245.  herePtr            Pointer to the internal data control for this file 
  3246.  codePage           Code page used when the index file was created (the actual 
  3247.                     code page) 
  3248.  countryCode        Country code used when the index file was created (the 
  3249.                     actual country code) 
  3250.  CTptr              Pointer to the collate sequence table used for NLS sorting 
  3251.                     (each index file has its own sequence table) or NULL if not 
  3252.                     an NLS index 
  3253.  nodeSize           Size of an index node, 512, 1024, or 2048 bytes, as 
  3254.                     specified during create 
  3255.  sortFunction       The index sort-compare method (low word) and the sort flags 
  3256.                     (high word), with sort-compare values 1-9 being intrinsic, 
  3257.                     and 10-19 being custom functions; the DUPS_ALLOWED flag is 
  3258.                     bit0 of the high word (allowed if set) 
  3259.  lockCount          Number of full-locks in force (locked on first, unlocked on 
  3260.                     last) 
  3261.  
  3262.  Typically, your program tracks whether a particular handle belongs to an index 
  3263.  file or a data file.  In cases where this is not possible, call the 
  3264.  STAT_HANDLE_XB routine to determine what file type a handle is. 
  3265.  
  3266.  Note:  In network environments, you should have an exclusive lock on the index 
  3267.  file before using this routine to ensure that the information is current. 
  3268.  This routine is not mutex-protected.  During the call, the file handle must 
  3269.  not be closed by another thread. 
  3270.  
  3271.  
  3272. ΓòÉΓòÉΓòÉ 9.23. READ_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3273.  
  3274. Pack: HANDLEPACK               Source Example 
  3275.  
  3276.      IN               OUT
  3277.    HP.func          HP.stat
  3278.    HP.handle
  3279.  
  3280.  Reload the disk copy of the index header for the opened index file handle, 
  3281.  refreshing the in-memory copy. 
  3282.  
  3283.  Normally, this routine is not called directly but rather is done automatically 
  3284.  when you full-lock the file (LOCK_XB).  This routine does not refresh the 
  3285.  header if the current state is dirty (SIP.flags, bit0=1); it returns an error 
  3286.  if tried. Since it is recommended that a full-lock be in force before using 
  3287.  this routine (shared or exclusive), and since a full-lock always reloads the 
  3288.  header anyway, calling this routine should never be required.  If ever there 
  3289.  is a reason to use this routine without having a full-lock in force, then, of 
  3290.  course, you may need to.  However, it is not wise to reload the header without 
  3291.  a full-lock (which locks the header).  If you are using your own lock 
  3292.  routines, this call will be very useful. 
  3293.  
  3294.  In single-user, single-tasking systems this routine is not needed.  However, 
  3295.  in a multi-user or multi-tasking system it's possible, and desirable, for two 
  3296.  or more programs to use the same data file.  Consider this scenario: An index 
  3297.  file has 100 keys.  Two programs access this index file, both opening it. 
  3298.  Program 1 locks the file, adds a new key, then flushes and unlocks the file. 
  3299.  Program 1 knows that there are now 101 keys in the file.  However, Program 2 
  3300.  is not aware of the changes that Program 1 made--it thinks that there are 
  3301.  still 100 keys in the file.  This out-of-sync situation is easily remedied by 
  3302.  having Program 2 reload the index header from the file on disk. 
  3303.  
  3304.  How does Program 2 know that it needs to reload the header? It doesn't. 
  3305.  Instead, BULLET uses a simple, yet effective, approach when dealing with this. 
  3306.  When BULLET full-locks a file, it automatically reloads the header using this 
  3307.  routine.  When removing the full-lock, BULLET automatically flushes the header 
  3308.  using FLUSH_INDEX_HEADER_XB (unless the current lock is a shared lock 
  3309.  (SIP.flags bit2=1)). 
  3310.  
  3311.  
  3312. ΓòÉΓòÉΓòÉ 9.24. FLUSH_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3313.  
  3314. Pack: HANDLEPACK               Source Example 
  3315.  
  3316.      IN               OUT
  3317.    HP.func          HP.stat
  3318.    HP.handle
  3319.  
  3320.  Write the in-memory copy of the index header for the opened index file handle 
  3321.  to disk.  The actual write occurs only if the header has been changed. This 
  3322.  ensures that the index header on disk matches exactly the index header that is 
  3323.  being maintained by BULLET. 
  3324.  
  3325.  Normally, this routine is not called directly but rather is done automatically 
  3326.  when you unlock the file (UNLOCK_XB).  This routine does not write out the 
  3327.  header if the current lock state is shared (SIP.flags, bit2=1); it returns an 
  3328.  error if tried.  Unlocking a full-lock performs a flush automatically, and so 
  3329.  you may never need to explicitly call this routine.  Also, when relocking from 
  3330.  an exclusive full-lock to a shared full-lock, an automatic flush is performed. 
  3331.  
  3332.  Assume the following: An index file with 100 keys.  Your program opens the 
  3333.  index file and adds 1 key.  Physically, there are 101 keys on disk.  However, 
  3334.  the header image of the index file on disk still reads 100 keys.  This isn't a 
  3335.  problem; BULLET uses its in-memory copy of the index header and the in-memory 
  3336.  copy does read 101 keys.  But, if there were a system failure after the key 
  3337.  add, the disk image of the header would not get updated since the disk image 
  3338.  is written only on a CLOSE_ or FLUSH_INDEX_XB, or on EXIT_XB (and also prior 
  3339.  to REINDEX_XB).  After the system restarts, BULLET opens the file, reads the 
  3340.  header and thinks that there are 100 keys.  You lost a key.  Now, if after 
  3341.  that key was added, your program issues a FLUSH_INDEX_HEADER_XB, the header on 
  3342.  disk is refreshed with the in-memory copy, keeping the two in sync.  The 
  3343.  routine updates the directory entry, keeping things neat there as well (file 
  3344.  size).  Still, it doesn't come without cost: flushing will take additional 
  3345.  time, therefore, you may elect to flush periodically, or whenever the system 
  3346.  is idle. 
  3347.  
  3348.  Note:  You should have a full-lock on the file before using this routine. 
  3349.  
  3350.  
  3351. ΓòÉΓòÉΓòÉ 9.25. COPY_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3352.  
  3353. Pack: COPYPACK                 Source Example 
  3354.  
  3355.      IN               OUT
  3356.    CP.func          CP.stat
  3357.    CP.handle
  3358.    CP.filenamePtr
  3359.  
  3360.  Copy the index file structure of an open index file to another file. 
  3361.  
  3362.  This routine duplicates the structure of an existing index file without having 
  3363.  to re-specify the information needed by CREATE_INDEX_XB. The resultant index 
  3364.  file will be exactly like the source, including sort function and key 
  3365.  expression.  It contains 0 keys. 
  3366.  
  3367.  
  3368. ΓòÉΓòÉΓòÉ 9.26. ZAP_INDEX_HEADER_XB ΓòÉΓòÉΓòÉ
  3369.  
  3370. Pack: HANDLEPACK               Source Example 
  3371.  
  3372.      IN               OUT
  3373.    HP.func          HP.stat
  3374.    HP.handle
  3375.  
  3376.  Delete all keys from an index file. 
  3377.  
  3378.  This routine is similar to COPY_INDEX_HEADER_XB except for one major 
  3379.  difference: All keys in the source file are physically deleted. 
  3380.  
  3381.  If you have an index file with 100 keys and issue ZAP_INDEX_HEADER_XB, all 100 
  3382.  keys will be physically deleted and the file truncated to 0 keys. REINDEX_XB 
  3383.  can be used to rebuild the index file. 
  3384.  
  3385.  Note:  Since BULLET reindexes in place, the use of ZAP is not typically 
  3386.  needed. 
  3387.  
  3388.  
  3389. ΓòÉΓòÉΓòÉ 9.27. GET_DESCRIPTOR_XB ΓòÉΓòÉΓòÉ
  3390.  
  3391. Pack: DESCRIPTORPACK           Source Example 
  3392.  
  3393.      IN               OUT
  3394.    DP.func          DP.stat
  3395.    DP.fieldNumber   DP.fieldNumber
  3396.         -or-        DP.fieldOffset
  3397.    DP.FD.fieldName  DP.FD.fieldname
  3398.                     DP.FD.fieldType
  3399.                     DP.FD.fieldLen
  3400.                     DP.FD.fieldDC
  3401.  
  3402.  Get the field descriptor information for a field by fieldname or by field 
  3403.  position. 
  3404.  
  3405.  To get descriptor info by fieldname, set DP.fieldNumber=0 and set the 
  3406.  DP.FD.fieldname member to the fieldname string.  Fieldnames must be 
  3407.  0-terminated and 0-filled, and must be upper-case, with A-Z and _ valid 
  3408.  fieldname characters.  If the string matches a fieldname in the DBF descriptor 
  3409.  area, that field's descriptor info is returned in DP.FD, (FD is 
  3410.  FIELDDESCTYPE), and its position is returned in FD.fieldNumber. 
  3411.  
  3412.  To get descriptor info by field position (i.e., field number), set 
  3413.  DP.fieldNumber to the field's position.  The first is field #1. The "tag" 
  3414.  field is not considered a field.  If the position is valid (i.e., greater than 
  3415.  0 and not beyond the last field),that field's descriptor info is returned in 
  3416.  DP.FD. 
  3417.  
  3418.  This routine lets you work with unknown DBF files -- those created by another 
  3419.  program.  By reading each field descriptor, by number, from 1 to number of 
  3420.  fields (SDP.noFields), you can generate a run-time layout of the DBF file. 
  3421.  Alternatively, you can get input from your user for a fieldname, and locate 
  3422.  the descriptor by name. 
  3423.  
  3424.  Note:  If you need to add or delete a field, be sure to reindex all related 
  3425.  index files so that their key expressions can be re-evaluated. To do this, you 
  3426.  need to create a new data file and build it as you build any other new data 
  3427.  file.  Then, copy record-by-record from the old DBF to the new, using the old 
  3428.  record layout for reads, and the new record layout for writes.  After this, 
  3429.  reindex any index file related to the DBF file.  The old DBF file can then be 
  3430.  deleted. 
  3431.  
  3432.  If non-standard fields are used (i.e., non-char structure members to match 
  3433.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3434.  compiler more than likely will add padding to align on member-size boundaries. 
  3435.  This will result in a mis-match between your compiler structure and your DBF 
  3436.  structure (as described in fieldList[]).  To prevent this, place #pragma 
  3437.  pack(1) / #pragma pack() around your structures that BULLET uses.  Consult 
  3438.  your particular compiler for alternate methods if it does not support #pragma 
  3439.  pack. 
  3440.  
  3441.  
  3442. ΓòÉΓòÉΓòÉ 9.28. GET_RECORD_XB ΓòÉΓòÉΓòÉ
  3443.  
  3444. Pack: ACCESSPACK               Source Example 
  3445.  
  3446.      IN               OUT
  3447.    AP.func          AP.stat
  3448.    AP.handle        *AP.recPtr
  3449.    AP.recNo
  3450.    AP.recPtr
  3451.  
  3452.  Get the physical record from the data file into a data buffer. 
  3453.  
  3454.  The data buffer is typically a struct variable defined as the DBF record 
  3455.  itself is defined.  For example, if the DBF record has 2 fields, LNAME and 
  3456.  FNAME, each 25 characters, then then variable would be typed as: 
  3457.  
  3458.   struct rectype {
  3459.    CHAR  tag;             /* The Xbase DBF delete flag (must be included) */
  3460.    CHAR  lastName[25];    /* same length as first field's descriptor fieldLen */
  3461.    CHAR  firstName[25];   /* same length as second field's descriptor fieldLen */
  3462.   }; /* 51 */
  3463.   struct rectype recbuff;
  3464.  
  3465.  The first record is at AP.recNo=1.  The last is SDP.records, determined by 
  3466.  STAT_DATA_XB.  The buffer must be at least as large as the record length 
  3467.  (SDP.recordLength). 
  3468.  
  3469.  This method of accessing the data file does not use any indexing.  Generally, 
  3470.  this access method is not used except for special purposes (sequential 
  3471.  processing where order is not required).  The preferred method to access the 
  3472.  data is by one of the keyed GET_XB routines. 
  3473.  
  3474.  If non-standard fields are used (i.e., non-char structure members to match 
  3475.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3476.  compiler more than likely will add padding to align on member-size boundaries. 
  3477.  This will result in a mis-match between your compiler structure (rectype 
  3478.  above) and your DBF structure (as described in fieldList[]).  To prevent this, 
  3479.  place #pragma pack(1) / #pragma pack() around your structures that BULLET 
  3480.  uses.  Consult your particular compiler for alternate methods if it does not 
  3481.  support #pragma pack. 
  3482.  
  3483.  
  3484. ΓòÉΓòÉΓòÉ 9.29. ADD_RECORD_XB ΓòÉΓòÉΓòÉ
  3485.  
  3486. Pack: ACCESSPACK               Source Example 
  3487.  
  3488.      IN               OUT
  3489.    AP.func          AP.stat
  3490.    AP.handle        AP.recNo
  3491.    AP.recPtr
  3492.  
  3493.  Append the data record in the data buffer to the end of the DBF file. 
  3494.  
  3495.  This method of adding a record involves no indexing.  It is typically used to 
  3496.  build a data file en masse.  Indexing is deferred until all records have been 
  3497.  added, and then quickly indexed using REINDEX_XB. 
  3498.  
  3499.  Since ADD_RECORD_XB is extremely fast, if you have several thousand data 
  3500.  records to be added at once, appending records with this routine and 
  3501.  reindexing when all have been added using REINDEX_XB is often faster than 
  3502.  using INSERT_XB for each record to add. 
  3503.  
  3504.  The record number assigned to the record appended is determined by BULLET, and 
  3505.  that record number is returned in AP.recNo. 
  3506.  
  3507.  If non-standard fields are used (i.e., non-char structure members to match 
  3508.  non-ASCII data fields in your non-standard DBF), then be aware that your 
  3509.  compiler more than likely will adding padding to align on member-size 
  3510.  boundaries.  This will result in a mis-match between your compiler structure 
  3511.  and your DBF structure (as described in fieldList[]).  To prevent this, place 
  3512.  #pragma pack(1) / #pragma pack() around your structures that BULLET uses. 
  3513.  Consult your particular compiler for alternate methods if it does not support 
  3514.  #pragma pack. 
  3515.  
  3516.  
  3517. ΓòÉΓòÉΓòÉ 9.30. UPDATE_RECORD_XB ΓòÉΓòÉΓòÉ
  3518.  
  3519. Pack: ACCESSPACK               Source Example 
  3520.  
  3521.      IN               OUT
  3522.    AP.func          AP.stat
  3523.    AP.handle
  3524.    AP.recNo
  3525.    AP.recPtr
  3526.  
  3527.  Write the updated data record to the physical record number. 
  3528.  
  3529.  This method of updating a data record must not be used if any field being used 
  3530.  as a key field (i.e., part of the key expression) is changed. 
  3531.  
  3532.  This method of updating a record is very fast if you know that that update is 
  3533.  not going to alter any field used as a key in any index file that uses it. You 
  3534.  must, of course, first get the data record into the record buffer.  You can 
  3535.  then change it, and write the update out to disk using this routine. 
  3536.  
  3537.  If you need to change a field that is used as a key field, or part of one 
  3538.  (e.g., SUBSTR()), use the UPDATE_XB routine. 
  3539.  
  3540.  If you plan on reindexing with REINDEX_XB immediately after using this 
  3541.  routine, you may elect to update the data file using this method even if 
  3542.  changing any field used as a key, rather than UPDATE_XB.  This since UPDATE_XB 
  3543.  is very disk intensive.  However, if transaction support is needed (i.e., 
  3544.  updates are dependent on other updates), then UPDATE_XB should be used. 
  3545.  
  3546.  
  3547. ΓòÉΓòÉΓòÉ 9.31. DELETE_RECORD_XB ΓòÉΓòÉΓòÉ
  3548.  
  3549. Pack: ACCESSPACK               Source Example 
  3550.  
  3551.      IN               OUT
  3552.    AP.func          AP.stat
  3553.    AP.handle
  3554.    AP.recNo
  3555.  
  3556.  Tag the record at the physical record number as being deleted. 
  3557.  
  3558.  This does not tag any in-memory copies of the record so be sure to mark any 
  3559.  such copies as being deleted yourself. 
  3560.  
  3561.  The first byte of every DBF record is reserved for the tag field.  This tag is 
  3562.  a space (ASCII 32) if the record is normal, or a * (ASCII 42) if it's marked 
  3563.  as being deleted.  This delete tag is a reserved field in the DBF record and 
  3564.  as such is not defined as a formal field with a descriptor.  Make sure that 
  3565.  you define your in-memory buffers to reserve the first byte for the delete 
  3566.  tag. 
  3567.  
  3568.  The Xbase DBF standard doesn't physically remove records marked as deleted 
  3569.  from the data file.  It doesn't mark them as available/reusable either.  To 
  3570.  physically remove records marked as deleted use PACK_RECORDS_XB 
  3571.  
  3572.  Records can be temporarily marked as deleted during processing and then 
  3573.  recalled to normal status when completed, useful for flagging a record as 
  3574.  having been processed (for example, mass updating using UPDATE_XB).  The 
  3575.  GET_XB routines return the record number associated with a key (in AP.recNo), 
  3576.  and that record number can be used for this routine. 
  3577.  
  3578.  While the DELETE_RECORD_XB and UNDELETE_RECORD_XB routines provided in BULLET 
  3579.  use the * and SPACE characters only, you can use whatever character you want 
  3580.  in the tag field when you fill your record buffer structure's data.  Normally, 
  3581.  you set the tag field to SPACE (x.tag = ' ';), but, for example, if you want 
  3582.  to implement your own, program-level locking you can use the tag field as a 
  3583.  marker to indicate the record is locked (by using an 'L' character, or ID with 
  3584.  bit7=1, or whatever you can think of) and use the very fast UPDATE_RECORD_XB 
  3585.  to set it.  Another possibility is set to aside a field to be used as this, 
  3586.  say, along with the user ID of the lock owner. 
  3587.  
  3588.  The SKIP_TAG_SELECT item in SET_SYSVARS_XB can be set to have the REINDEX_XB 
  3589.  routine not place a key value into the index file if a record has a matching 
  3590.  tag field.  This may be useful if you want to, say, generate an ad hoc index 
  3591.  for only undeleted records. 
  3592.  
  3593.  
  3594. ΓòÉΓòÉΓòÉ 9.32. UNDELETE_RECORD_XB ΓòÉΓòÉΓòÉ
  3595.  
  3596. Pack: ACCESSPACK               Source Example 
  3597.  
  3598.      IN               OUT
  3599.    AP.func          AP.stat
  3600.    AP.handle
  3601.    AP.recNo
  3602.  
  3603.  Tag the record at the physical record number as being normal (not deleted). 
  3604.  
  3605.  This does not tag any in-memory copies of the record so be sure to mark any 
  3606.  such copies as being normal. 
  3607.  
  3608.  This routine removes the * character, as put there by DELETE_RECORD_XB, in the 
  3609.  tag field and replaces it with a SPACE.  The tag field is always overwritten 
  3610.  with a SPACE, regardless of what it was. 
  3611.  
  3612.  
  3613. ΓòÉΓòÉΓòÉ 9.33. PACK_RECORDS_XB ΓòÉΓòÉΓòÉ
  3614.  
  3615. Pack: ACCESSPACK               Source Example 
  3616.  
  3617.      IN               OUT
  3618.    AP.func          AP.stat
  3619.    AP.handle
  3620.  
  3621.  Rebuild the open DBF file by physically removing all records marked as 
  3622.  deleted. 
  3623.  
  3624.  Packing occurs in place using the existing file.  It is recommended that you 
  3625.  use BACKUP_FILE_XB to copy the current DBF file before using this routine in 
  3626.  case of a failure during the pack process. 
  3627.  
  3628.  The newly packed file is truncated to reflect the current, actual size.  All 
  3629.  records with the tag field set to * are removed from the file. 
  3630.  
  3631.  If there are index files for this DBF file, they must be reindexed after the 
  3632.  pack process by using REINDEX_XB. 
  3633.  
  3634.  Memo files are not affected by this routine.  Before packing, it is 
  3635.  recommended that you traverse the data file to be packed, and for records that 
  3636.  are to be deleted, check to see if there is a memo record. If there is, delete 
  3637.  the memo.  Do this for each such occurrence.  This way, orphaned memo records 
  3638.  will not take up permanent space in the memo file. 
  3639.  
  3640.  
  3641. ΓòÉΓòÉΓòÉ 9.34. DEBUMP_RECORD_XB ΓòÉΓòÉΓòÉ
  3642.  
  3643. Pack: ACCESSPACK               Source Example 
  3644.  
  3645.      IN               OUT
  3646.    AP.func          AP.stat
  3647.    AP.handle
  3648.    AP.recNo
  3649.  
  3650.  Remove the record identified by AP.recNo from the data file if and only if the 
  3651.  record is the last in the file. 
  3652.  
  3653.  Unlike DELETE_RECORD_XB, this routine physically removes a data record from 
  3654.  the DBF file, provided that the record to delete is the last. STAT_DATA_XB can 
  3655.  be used to identify the last record number (SDP.records is the last).  This, 
  3656.  when used after deleting any and all keys in all index files referencing this 
  3657.  record (see DELETE_KEY_XB), is useful if you are managing a transaction log 
  3658.  and need to back out changes made, beyond what BULLET performs. 
  3659.  
  3660.  If the record is not the last, alternate methods must be used. The simplest, 
  3661.  and often equally as good as physically deleting the record, is to just mark 
  3662.  the record as deleted using DELETE_RECORD_XB and let it remain in the file 
  3663.  until the next PACK_RECORDS_XB.  Another option is to overwrite the record's 
  3664.  data with SPACES, or other appropriate field data (such as HIGH-VALUES, and 
  3665.  use UPDATE_XB), if necessary.  This routine is the only method available to 
  3666.  physically remove a record from the file, short of using PACK_RECORDS_XB. 
  3667.  Removing a record with active keys referencing that record will result in an 
  3668.  access error (ERR_UNEXPECTED_EOF) when accessing that key with GET_XB 
  3669.  routines, or will generate stale results.  Remove any keys that reference this 
  3670.  record before deleting it. 
  3671.  
  3672.  
  3673. ΓòÉΓòÉΓòÉ 9.35. GET_MEMO_SIZE_XB ΓòÉΓòÉΓòÉ
  3674.  
  3675. Pack: MEMODATAPACK             Source Example 
  3676.  
  3677.      IN               OUT
  3678.    MDP.func         MDP.stat
  3679.    MDP.dbfHandle    MDP.memoBytes
  3680.    MDP.memoNo
  3681.  
  3682.  Get the number of bytes used by the memo at MDP.memoNo. 
  3683.  
  3684.  Memo file allocation is made in blocks, typically of 512 bytes each. 
  3685.  Therefore, a memo of 10 bytes uses 1 allocation block, as would a 500-byte 
  3686.  memo.  This size is stored with each memo record, and can be retrieved. 
  3687.  Before accessing a memo record, it's a good idea to retrieve the current size 
  3688.  of the memo so you know how large a buffer you may need if you intend to read 
  3689.  it all in, at one time, or even to just know how much to read, in total, 
  3690.  reading parts of it at a time. 
  3691.  
  3692.  The first memo is at MDP.memoNo=1.  The last memo number cannot be easily 
  3693.  determined, but generally this does not need to be known.  The memo number 
  3694.  identifying the memo's location is stored in the memo field area of the DBF 
  3695.  record.  It is stored as a text string (e.g., "0000000001").  This number is 
  3696.  the physical block number at which the memo starts.  Memos are always stored 
  3697.  in consecutive blocks, if more than a single block is needed.  For example, a 
  3698.  memo of 513 bytes uses two blocks, say, #1 and #2.  The next memo added would 
  3699.  use memo #3 (if #3 is available), rather than #2 since #2 was used by the 
  3700.  first memo.  Memo numbers may be reassigned (see UPDATE_MEMO_XB).  The highest 
  3701.  possible memo number is 589,822 (0x8FFFE).  With the standard 512-byte block 
  3702.  size, this allows a memo file to be up to 288MB.  If more memo data space is 
  3703.  needed, use a larger block size (e.g., 2KB block size allows over 1GB per memo 
  3704.  file). 
  3705.  
  3706.  Notice For All Memo Routines 
  3707.  
  3708.  In multitasking environments you should have a full-lock on the DBF file that 
  3709.  owns this memo file, or at least a record lock on the record that owns the 
  3710.  memo number.  In BULLET, locking is not performed on the memo file.  Instead, 
  3711.  the lock is implied when the lock is made on the DBF file.  This because a 
  3712.  memo file is for one DBF file alone, and so if you have a lock on the DBF 
  3713.  before accessing the memo file (for whatever reason), then no other process 
  3714.  may lock the DBF and also access the memo. 
  3715.  
  3716.  This works only if you restrict your access to the memo file if you have a 
  3717.  lock on the DBF master file (the DBF that this DBT memo file belongs to) or on 
  3718.  the DBF record.  For this routine, which only requires access to this memo 
  3719.  record, a record lock is sufficient since no writing is performed.  Further, a 
  3720.  shared lock is all that is required.  This because all that is required to 
  3721.  keep from stepping on other process's toes is that it be known that the 
  3722.  current memo header info (for this memo record), as known to this process, is 
  3723.  the current state of this memo.  In other words, it must be true that the memo 
  3724.  file state on disk exactly matches the memo file state in memory.  With a lock 
  3725.  in place, no other process may gain write access to change this memo, "out 
  3726.  from under you".  A shared lock does allow the other process to read this 
  3727.  memo, and that may be used if no writing is needed. 
  3728.  
  3729.  Each memo routine following states its lock requirements (exclusive full lock, 
  3730.  shared full lock, exclusive record lock, or shared record lock). 
  3731.  
  3732.  
  3733. ΓòÉΓòÉΓòÉ 9.36. GET_MEMO_XB ΓòÉΓòÉΓòÉ
  3734.  
  3735. Pack: MEMODATAPACK             Source Example 
  3736.  
  3737.      IN               OUT
  3738.    MDP.func         MDP.stat
  3739.    MDP.dbfHandle    *MDP.memoPtr
  3740.    MDP.memoNo       MDP.memoBytes
  3741.    MDP.memoPtr
  3742.    MDP.memoOffset
  3743.    MDP.memoBytes
  3744.  
  3745.  Read the specified number of bytes of the memo, starting at the offset, into 
  3746.  the buffer.  The actual number of bytes read is returned. 
  3747.  
  3748.  Use GET_MEMO_SIZE_XB to determine that total number of bytes you may need to 
  3749.  read.  With that, you can allocate a buffer of that size to read the entire 
  3750.  memo into.  Or, you can read chunks of the memo at a time, up to the number of 
  3751.  bytes in the memo. 
  3752.  
  3753.  The number of bytes actually read (and stored starting at MDP.memoPtr) is 
  3754.  returned in MDP.memoBytes (overwriting the value you placed there).  If the 
  3755.  number of bytes requested is not the same as the number of bytes returned, you 
  3756.  attempted to read beyond the end of the memo.  BULLET does not return an error 
  3757.  if you try this, which is SOP for file reads, so check the two if you need to 
  3758.  verify this.  An error is returned, however, if you attempt to read at a 
  3759.  starting offset beyond the end of the actual memo data (i.e., MDP.memoOffset > 
  3760.  memo's data size). 
  3761.  
  3762.  It's recommended that a lock be in force on either the DBF (full-lock) or on 
  3763.  the record that this memo belongs to.  A shared lock is okay since no writing 
  3764.  is done. 
  3765.  
  3766.  
  3767. ΓòÉΓòÉΓòÉ 9.37. ADD_MEMO_XB ΓòÉΓòÉΓòÉ
  3768.  
  3769. Pack: MEMODATAPACK             Source Example 
  3770.  
  3771.      IN               OUT
  3772.    MDP.func         MDP.stat
  3773.    MDP.dbfHandle    MDP.memoNo
  3774.    MDP.memoPtr
  3775.    MDP.memoBytes
  3776.  
  3777.  Add the data from the buffer for the specified bytes to a new memo.  The memo 
  3778.  number used is returned. 
  3779.  
  3780.  Any data can be stored in a memo.  The memo number returned can be any value; 
  3781.  it can even be less than the previous add's memo number.  The reason for this 
  3782.  is that an avail-list is kept for the memo file, and any deleted or otherwise 
  3783.  freed blocks become available for re-use.  The memo is stored in the first 
  3784.  contiguous group of free blocks large enough to satisfy the request.  For 
  3785.  example, if MDP.memoBytes is from 1 to (blockSize-8) bytes, the first 
  3786.  available block is used.  If the size needed is greater than 1 block, then the 
  3787.  avail-list is walked and the first contiguous group large enough to satisfy 
  3788.  the request is used.  If none of the avail-list groups is large enough, 
  3789.  ultimately, the new memo data is appended to the end of the file.  This is 
  3790.  also done if there are no avail-list items at all, such as in a memo file that 
  3791.  has never had deletes or updates. 
  3792.  
  3793.  The returned memo is a binary block number (ULONG).  This value should be 
  3794.  converted into an ASCII string (sprintf can be used) and stored in the DBF 
  3795.  data record, in the memo field.  The string should be of the form, 
  3796.  '0000000001' (for MDP.memoNo=1), with leading zeros.  This data record should 
  3797.  then be written to disk using UPDATE_RECORD_XB. Since BULLET can be used in 
  3798.  non-standard Xbase mode, where binary field values can be used, you can omit 
  3799.  the conversion from binary to ASCII if a standard DBF is not required. 
  3800.  Likewise, when accessing a memo, the conversion from ASCII to binary would not 
  3801.  be required. 
  3802.  
  3803.  It's recommended that a lock be in force on the DBF (full-lock).  A shared 
  3804.  lock may not be used since writing to the memo file, and the DBF record, is 
  3805.  required.  A full lock is required since the memo file header is read and 
  3806.  written. 
  3807.  
  3808.  
  3809. ΓòÉΓòÉΓòÉ 9.38. UPDATE_MEMO_XB ΓòÉΓòÉΓòÉ
  3810.  
  3811. Pack: MEMODATAPACK             Source Example 
  3812.  
  3813.      IN               OUT
  3814.    MDP.func         MDP.stat
  3815.    MDP.dbfHandle    MDP.memoNo
  3816.    MDP.memoNo
  3817.    MDP.memoPtr
  3818.    MDP.memoOffset
  3819.    MDP.memoBytes
  3820.  
  3821.  Update an existing memo.  The update can overwrite current data, append new 
  3822.  data extending the current size, or it can shrink the current size. 
  3823.  
  3824.  Appending data so that the memo is extended may result in a new memo number 
  3825.  returned.  The original memo blocks are made available for reuse (deleted). 
  3826.  Shrinking will not change the memo number, but unused blocks from the shrink 
  3827.  are made available for reuse. 
  3828.  
  3829.  If you want to change anything in the memo at MDP.memoNo, locate its position 
  3830.  within the memo with MDP.memoOffset and set the size in MDP.memoBytes. The 
  3831.  first data byte of a memo is located at MDP.offset=0.  There are 8 bytes of 
  3832.  overhead per memo record (any number of blocks still has only the 8 bytes of 
  3833.  overhead), but these are transparent to any memo access you do. The bytes at 
  3834.  MDP.memoPtr overwrite the current memo data at the position specified.  For 
  3835.  example, if you want to change the first 5 bytes of the first memo, set 
  3836.  MDP.memoNo=1, MDP.memoPtr=yourNewData, MDP.memoOffset=0, and MDP.memoBytes=5. 
  3837.  On return, MDP.memoNo is going to be the same as it was before the update, 
  3838.  since you are not extending the memo size in this example.  Nothing further 
  3839.  needs to be done; the memo is updated. 
  3840.  
  3841.  If you want to add new memo data to an existing memo at MDP.memoNo, such as 
  3842.  adding another line item, or problem report paragraph, etc., set 
  3843.  MDP.memoOffset=theCurrentMemoSize (this locates to the end of the current memo 
  3844.  data), MDP.memoBytes=bytesYouWantToAppend, and MDP.memoPtr=yourDataToAppend. 
  3845.  If the old data size plus your newly added data still fits inside the last 
  3846.  memo block previously used, MDP.memoNo is returned the same as it was on 
  3847.  entry.  However, if the new data requires that more blocks be allocated, the 
  3848.  entire memo is relocated to the next contiguous block group that is large 
  3849.  enough to store the data.  That new block number is returned in MDP.memoNo, 
  3850.  and the old block number and all its blocks are placed on the top of the 
  3851.  avail-list. 
  3852.  
  3853.  If you want to shrink the size as reported by GET_MEMO_SIZE_XB from an 
  3854.  existing memo at MDP.memoNo, set MDP.memoBytes=newSizeYouWant, and 
  3855.  MDP.memoPtr=NULL.  This means that you should have, before making this shrink 
  3856.  call, updated the memo data that occurs within this new size to be the data 
  3857.  size you want to be in the memo.  For example, if you have 10 line items, say, 
  3858.  each 60 bytes long, and want to remove line item #5, you could do it by 
  3859.  reading all 10 line items to memory, moving line items #6 to 10 down one (so 
  3860.  they are now line items #5 to 9, effectively removing old line item #5), and 
  3861.  update the memo (by using memoOffset=0 and memoBytes=9*60).  After this, 
  3862.  though, you still have 10*60 bytes as the memo size (old line item #10 is now 
  3863.  at #9 and still at #10).  Since you want the size to reflect the real data in 
  3864.  the memo, set MDP.memoBytes=90, MDP.memoPtr=NULL, and update this memo number. 
  3865.  Only the memo's size is affected by this particular update.  The size 
  3866.  specified must be smaller than the original size, or an error is returned. 
  3867.  
  3868.  It's recommended that a lock be in force on the DBF (full-lock).  A record 
  3869.  lock should not be used if the update may result in blocks being moved, or the 
  3870.  memo being shrunk by a full block or more.  A shared lock may not be used 
  3871.  since writing to the memo file, and to the DBF record if MDP.memoNo is new, is 
  3872.  required. 
  3873.  
  3874.  
  3875. ΓòÉΓòÉΓòÉ 9.39. DELETE_MEMO_XB ΓòÉΓòÉΓòÉ
  3876.  
  3877. Pack: MEMODATAPACK             Source Example 
  3878.  
  3879.      IN               OUT
  3880.    MDP.func         MDP.stat
  3881.    MDP.dbfHandle
  3882.    MDP.memoNo
  3883.  
  3884.  The memo and all its blocks are made available for reuse. 
  3885.  
  3886.  Before using PACK_RECORDS_XB, you should run through all DBF records and check 
  3887.  for those records that are deleted (record.tag='*') to be sure that any memo 
  3888.  belong to those records are deleted from the memo file.  If this is not done, 
  3889.  orphaned memo records -- those that do not have a DBF record memo field 
  3890.  pointing to it, may be left in the memo file (forever!). 
  3891.  
  3892.  After deleting a memo record, update the DBF record's memo field by writing 
  3893.  <SPACES> (ASCII 32) to the memo field member.  Update this to disk with 
  3894.  UPDATE_RECORD_XB as soon as possible (and before unlocking).  A memo field 
  3895.  with no current memo record is indicated by spaces ('0000000000' should not be 
  3896.  used). 
  3897.  
  3898.  It's recommended that a lock be in force on the DBF (full-lock).  Neither a 
  3899.  record lock nor a shared lock may be used since writing to the memo file 
  3900.  header and the DBF record is required. 
  3901.  
  3902.  
  3903. ΓòÉΓòÉΓòÉ 9.40. MEMO_BYPASS_XB ΓòÉΓòÉΓòÉ
  3904.  
  3905. Pack: MEMODATAPACK             Source Example 
  3906.  
  3907.      IN               OUT
  3908.    MDP.func         MDP.stat
  3909.    MDP.dbfHandle
  3910.    MDP.memoBypass
  3911.  
  3912.  Memo files are created, opened, closed, and flushed/reloaded by their 
  3913.  corresponding DBF data file action.  To perform these tasks asynchronously, 
  3914.  this routine is used.  Bypass routines are: 
  3915.  
  3916.      MDP.memoBypass      Value
  3917.    BYPASS_CREATE_MEMO        1
  3918.    BYPASS_OPEN_MEMO          2
  3919.    BYPASS_CLOSE_MEMO         3
  3920.    BYPASS_READ_MEMO_HEADER   4
  3921.    BYPASS_FLUSH_MEMO_HEADER  5
  3922.  
  3923.  All bypass routines require the handle of the DBF file that this memo is for. 
  3924.  Nothing is returned here, except the result code.  The memo handle from the 
  3925.  open is stored internally, but is available by using STAT_DATA_XB and checking 
  3926.  SDP.memoHandle.  However, none of the BULLET memo routines use the memo handle 
  3927.  directly; all access to the memo file is through the master DBF file handle. 
  3928.  
  3929.  No data is required for input other than the DBF handle and memo bypass 
  3930.  routine to perform (see table above).  All required info is obtained from the 
  3931.  DBF file's information.  You may use an alternate block size, as set via 
  3932.  SET_SYSVARS_XB. 
  3933.  
  3934.  Generally, there is no need to call these routines using this bypass. However, 
  3935.  if you need to create a memo file anew (say, after the initial DBF was 
  3936.  created), and then open it, using these routines is the easiest way to 
  3937.  proceed. 
  3938.  
  3939.  Note:  When creating a memo via the bypass method, the file ID is altered to 
  3940.  indicate that the DBF has a DBT memo file.  The file ID is the first byte of 
  3941.  the DBF file.  The ID is changed by OR'ing 0x88h with the current file ID 
  3942.  value.  The next flush or close updates the disk image of the DBF with the new 
  3943.  file ID.  The next DBF open, then, also opens the DBT memo file created here. 
  3944.  Be sure to always keep the DBT and DBF pairs in the same directory, if moved. 
  3945.  
  3946.  Since the DBF file is already open (and must be to use any of these routines), 
  3947.  you must use the open bypass routine to open the memo if you plan on using it. 
  3948.  Either that, or close the DBF after you've create the memo file, and simply 
  3949.  re-open the DBF, which also, now, opens the DBT memo file. 
  3950.  
  3951.  The other available bypass routines: close, read, and flush, typically will 
  3952.  not be used from this bypass routine.  These operations are done automatically 
  3953.  when their corresponding DBF action is performed, and have little 
  3954.  functionality used on their own. 
  3955.  
  3956.  Before using BYPASS_READ_MEMO_HEADER or BYPASS_FLUSH_MEMO_HEADER, it's 
  3957.  recommended that a lock be in force on the DBF (full-lock). A shared lock can 
  3958.  be used for BYPASS_READ_MEMO_HEADER, but it must be a full lock. 
  3959.  
  3960.  
  3961. ΓòÉΓòÉΓòÉ 9.41. FIRST_KEY_XB ΓòÉΓòÉΓòÉ
  3962.  
  3963. Pack: ACCESSPACK               Source Example 
  3964.  
  3965.      IN               OUT
  3966.    AP.func          AP.stat
  3967.    AP.handle        AP.recNo
  3968.    AP.keyPtr        *AP.keyPtr
  3969.  
  3970.  Retrieve the first key in index order from the index file. 
  3971.  
  3972.  This routine does not access the DBF file and so does not retrieve the data 
  3973.  record.  What it does do is locate the first logical key of the index file, 
  3974.  returning it, and also returning the record number within the DBF that the key 
  3975.  indexes. 
  3976.  
  3977.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  3978.  preferred method, however, is to use GET_FIRST_XB, which combines these 
  3979.  operations. 
  3980.  
  3981.  The key returned includes an enumerator if the index file allows duplicate 
  3982.  keys. 
  3983.  
  3984.  This routine is typically used to position the index file to the first key so 
  3985.  as to allow forward in-order access to the keys by using NEXT_KEY_XB. 
  3986.  
  3987.  If an external data file was specified in CREATE_INDEX_XB, the record number 
  3988.  returned by this routine does not refer to a DBF record, but rather is the 
  3989.  value supplied when the key was stored.  This permits index access to your 
  3990.  data files (data files which are not maintained by BULLET, but by you). 
  3991.  
  3992.  
  3993. ΓòÉΓòÉΓòÉ 9.42. EQUAL_KEY_XB ΓòÉΓòÉΓòÉ
  3994.  
  3995. Pack: ACCESSPACK               Source Example 
  3996.  
  3997.      IN               OUT
  3998.    AP.func          AP.stat
  3999.    AP.handle        AP.recNo
  4000.    AP.keyPtr
  4001.  
  4002.  Search for the exact key in the index file. 
  4003.  
  4004.  This routine does not access the DBF file and so does not retrieve the data 
  4005.  record.  What it does do is search for the key in the index, and if found, 
  4006.  returns the record number within the DBF that the key indexes.  The key must 
  4007.  be an exact match, including the enumerator word if the index file is using 
  4008.  non-unique keys. 
  4009.  
  4010.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4011.  preferred method, however, is to use GET_EQUAL_XB, which combines these 
  4012.  operations. 
  4013.  
  4014.  This routine returns no key in *keyPtr since, by definition, you already have 
  4015.  the key in the key buffer if this routine succeeds. 
  4016.  
  4017.  This routine finds only an exact match to the specified key (including the 
  4018.  enumerator if applicable).  However, even if the exact key is not found, the 
  4019.  index file is positioned so that a NEXT_KEY_XB retrieves the key that would 
  4020.  have followed the unmatched specified key.  For example, if the key to match 
  4021.  were "KINGS" (a partial key, say, with \0\0 after the S), EQUAL_KEY_XB would 
  4022.  return a key not found error (since no exact match was found).  If you were to 
  4023.  now do a NEXT_KEY_XB, the next key logically ordered after "KINGS" would be 
  4024.  returned.  Let's say "KINGSTON" was the next.  That key value, including 
  4025.  enumerator if any, and the key's record number is returned from the 
  4026.  NEXT_KEY_XB call.  This technique lets you position anywhere in the index file 
  4027.  to narrow down any manual searches (for instance, if you're looking for a key 
  4028.  but aren't sure of the exact spelling). 
  4029.  
  4030.  Note:  When using the partial key technique shown above, be sure to set the 
  4031.  unspecified characters of the key to \0, or at least the two bytes immediately 
  4032.  following your search criterion.  This for both unique and non-unique index 
  4033.  files.  This is to ensure that the key located is the first key matching your 
  4034.  search criterion. 
  4035.  
  4036.  
  4037. ΓòÉΓòÉΓòÉ 9.43. NEXT_KEY_XB ΓòÉΓòÉΓòÉ
  4038.  
  4039. Pack: ACCESSPACK               Source Example 
  4040.  
  4041.      IN               OUT
  4042.    AP.func          AP.stat
  4043.    AP.handle        AP.recNo
  4044.    AP.keyPtr        *AP.keyPtr
  4045.  
  4046.  Retrieve the next key in index order from the index file. 
  4047.  
  4048.  This routine does not access the DBF file and so does not retrieve the data 
  4049.  record.  What it does do is retrieve the next key of the index, returning it, 
  4050.  and also returning the record number within the DBF that the key indexes. 
  4051.  
  4052.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4053.  preferred method, however, is to use GET_NEXT_XB, which combines these 
  4054.  operations. 
  4055.  
  4056.  The key returned includes an enumerator if the index file allows duplicates. 
  4057.  
  4058.  This routine is typically called after the index file has first been 
  4059.  positioned to a known key using either FIRST_KEY_XB or EQUAL_KEY_XB, or after 
  4060.  a previous NEXT_KEY_XB or even PREV_KEY_XB.  What it basically does is get the 
  4061.  key following the current key, and then make that key the new current key. ________________________________________________
  4062.  
  4063.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4064.  based on a given starting point.  This simplifies index access in 
  4065.  multi-threaded code, where another thread may have altered the last key 
  4066.  accessed in the index file.  This mode lets you set a starting point for the 
  4067.  operation by supplying in AP.keyPtr the key value to start at. 
  4068.  
  4069.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4070.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4071.  accesses that same index file handle, and performs some other access, where 
  4072.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4073.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4074.  however, it very likely won't since the second thread has altered the last 
  4075.  accessed key for that file handle.  By using the atomic mode for key access, 
  4076.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4077.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4078.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4079.  operation.  This is performed within the Bullet kernel, and so won't be 
  4080.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4081.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4082.  accessed key.  This will always be the case unless uninitialized, or you are 
  4083.  using global variables for your threads' AP (AccessPack).  On return from the 
  4084.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4085.  
  4086.  Note:  You must supply a valid key value for this atomic access mode. 
  4087.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4088.  have the starting point for the operation (i.e., the last accessed key).  You 
  4089.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4090.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4091.  reverts to the internally-stored last key accessed as the starting point. 
  4092.  
  4093.  
  4094. ΓòÉΓòÉΓòÉ 9.44. PREV_KEY_XB ΓòÉΓòÉΓòÉ
  4095.  
  4096. Pack: ACCESSPACK               Source Example 
  4097.  
  4098.      IN               OUT
  4099.    AP.func          AP.stat
  4100.    AP.handle        AP.recNo
  4101.    AP.keyPtr        *AP.keyPtr
  4102.  
  4103.  Retrieve the previous key in index order from the index file. 
  4104.  
  4105.  This routine does not access the DBF file and so does not retrieve the data 
  4106.  record.  What it does do is retrieve the previous key of the index, returning 
  4107.  it and also returning the record number within the DBF that the key indexes. 
  4108.  
  4109.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4110.  preferred method, however, is to use GET_PREV_XB, which combines these 
  4111.  operations. 
  4112.  
  4113.  The key returned includes an enumerator if the index file allows duplicates. 
  4114.  
  4115.  This routine is typically called after the index file has first been 
  4116.  positioned to a known key using either LAST_KEY_XB or EQUAL_KEY_XB, or after a 
  4117.  previous PREV_KEY_XB or even NEXT_KEY_XB.  What it basically does is to get 
  4118.  the key previous the current key, and then make that key the new current key. ________________________________________________
  4119.  
  4120.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4121.  based on a given starting point.  This simplifies index access in 
  4122.  multi-threaded code, where another thread may have altered the last key 
  4123.  accessed in the index file.  This mode lets you set a starting point for the 
  4124.  operation by supplying in AP.keyPtr the key value to start at. 
  4125.  
  4126.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4127.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4128.  accesses that same index file handle, and performs some other access, where 
  4129.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4130.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4131.  however, it very likely won't since the second thread has altered the last 
  4132.  accessed key for that file handle.  By using the atomic mode for key access, 
  4133.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4134.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4135.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4136.  operation.  This is performed within the Bullet kernel, and so won't be 
  4137.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4138.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4139.  accessed key.  This will always be the case unless uninitialized, or you are 
  4140.  using global variables for your threads' AP (AccessPack).  On return from the 
  4141.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4142.  
  4143.  Note:  You must supply a valid key value for this atomic access mode. 
  4144.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4145.  have the starting point for the operation (i.e., the last accessed key).  You 
  4146.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4147.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4148.  reverts to the internally-stored last key accessed as the starting point. 
  4149.  
  4150.  
  4151. ΓòÉΓòÉΓòÉ 9.45. LAST_KEY_XB ΓòÉΓòÉΓòÉ
  4152.  
  4153. Pack: ACCESSPACK               Source Example 
  4154.  
  4155.      IN               OUT
  4156.    AP.func          AP.stat
  4157.    AP.handle        AP.recNo
  4158.    AP.keyPtr        *AP.keyPtr
  4159.  
  4160.  Retrieve the last key in index order from the index file. 
  4161.  
  4162.  This routine does not access the DBF file and so does not retrieve the data 
  4163.  record.  What it does do is locate the last key of the index, returning it, 
  4164.  and also returning the record number within the DBF that the key indexes. 
  4165.  
  4166.  To retrieve the data record you can use the GET_RECORD_XB routine.  The 
  4167.  preferred method, however, is to use GET_LAST_XB, which combines these 
  4168.  operations. 
  4169.  
  4170.  The key returned includes an enumerator if the index file allows duplicates. 
  4171.  
  4172.  This routine is typically used to position the index file to the last key so 
  4173.  as to allow reverse in-order access to the keys by using PREV_KEY_XB. 
  4174.  
  4175.  
  4176. ΓòÉΓòÉΓòÉ 9.46. STORE_KEY_XB ΓòÉΓòÉΓòÉ
  4177.  
  4178. Pack: ACCESSPACK               Source Example 
  4179.  
  4180.      IN               OUT
  4181.    AP.func          AP.stat
  4182.    AP.handle
  4183.    AP.recNo
  4184.    AP.keyPtr
  4185.  
  4186.  Insert the key into the index file in proper key order. 
  4187.  
  4188.  This routine does not add the data record to the DBF file.  It only inserts 
  4189.  the key and record number into the index file.  Use INSERT_XB instead. 
  4190.  
  4191.  To do a complete data record and key insert, use ADD_RECORD_XB to add the data 
  4192.  record to the DBF, BUILD_KEY_XB to construct the key, then STORE_KEY_XB to 
  4193.  insert the key and record number information into the index file.  If that key 
  4194.  already exists and the file allows duplicate keys, attach the proper 
  4195.  enumerator word and retry STORE_KEY_XB.  INSERT_XB does this automatically. 
  4196.  
  4197.  
  4198. ΓòÉΓòÉΓòÉ 9.47. DELETE_KEY_XB ΓòÉΓòÉΓòÉ
  4199.  
  4200. Pack: ACCESSPACK               Source Example 
  4201.  
  4202.      IN               OUT
  4203.    AP.func          AP.stat
  4204.    AP.handle        AP.recNo
  4205.    AP.keyPtr
  4206.  
  4207.  Physically remove the specified key from the index file. 
  4208.  
  4209.  This routine requires an exact key match for all bytes of the key, including 
  4210.  the enumerator word if duplicate keys are allowed. 
  4211.  
  4212.  Typically, this routine would seldom be used since deleted DBF data records 
  4213.  are only physically deleted during a PACK_RECORDS_XB operation, after which a 
  4214.  REINDEX_XB is done. It is useful if you are managing a transaction log and 
  4215.  need to back out changes made, beyond what BULLET performs.  Also see 
  4216.  DEBUMP_RECORD_XB. If you have non-unique keys (where DUPS_ALLOWED is true), 
  4217.  you may have several keys that match your criterion, and only differ in their 
  4218.  enumerator.  To identify which key, then, goes to a particular DBF record, 
  4219.  compare that key's AP.recNo with the number of your DBF record.  If they are 
  4220.  the same, then this key belongs to that record.  Use either the KEY_XB or the 
  4221.  GET_XB routines, then, before using this routine.  In other words, use this 
  4222.  routine only after you have identified exactly the key to delete, and for the 
  4223.  exact data record.  Once you have the record number, you can locate its key by 
  4224.  using GET_KEY_FOR_RECORD_XB. 
  4225.  
  4226.  
  4227. ΓòÉΓòÉΓòÉ 9.48. BUILD_KEY_XB ΓòÉΓòÉΓòÉ
  4228.  
  4229. Pack: ACCESSPACK               Source Example 
  4230.  
  4231.      IN               OUT
  4232.    AP.func          AP.stat
  4233.    AP.handle        *AP.keyPtr
  4234.    AP.recPtr
  4235.    AP.keyPtr
  4236.  
  4237.  Build the key for the specified data record based on the key expression for 
  4238.  the index file.  If the index file allows duplicate keys, a 0-value enumerator 
  4239.  is attached. 
  4240.  
  4241.  This routine, like most of the mid-level routines, typically would not be used 
  4242.  since the high-level access routines take care of this detail automatically. 
  4243.  If used, it normally would be used prior to STORE_KEY_XB. 
  4244.  
  4245.  This routine can be replaced.  See Custom Build-Key Routine. 
  4246.  
  4247.  Note:  If DUPS_ALLOWED, this routine always sets the enumerator to \0\0. 
  4248.  Enumerator management, which is used to guarantee a unique key, is performed 
  4249.  only when the INSERT_XB routine is used. 
  4250.  
  4251.  
  4252. ΓòÉΓòÉΓòÉ 9.49. GET_CURRENT_KEY_XB ΓòÉΓòÉΓòÉ
  4253.  
  4254. Pack: ACCESSPACK               Source Example 
  4255.  
  4256.      IN               OUT
  4257.    AP.func          AP.stat
  4258.    AP.handle        AP.recNo
  4259.    AP.keyPtr        *AP.keyPtr
  4260.  
  4261.  Retrieve the current key value for the specified index file handle and also 
  4262.  the data record number that it indexes. The key value includes the enumerator 
  4263.  if applicable. 
  4264.  
  4265.  This routine is useful in that it retrieves, on demand, the actual key value 
  4266.  of the last accessed key in the index file (and the data record number 
  4267.  associated with that key). STAT_INDEX_XB returns this information, too. 
  4268.  
  4269.  
  4270. ΓòÉΓòÉΓòÉ 9.50. GET_KEY_FOR_RECORD_XB ΓòÉΓòÉΓòÉ
  4271.  
  4272. Pack: ACCESSPACK               Source Example 
  4273.  
  4274.      IN               OUT
  4275.    AP.func          AP.stat
  4276.    AP.handle        *AP.keyPtr
  4277.    AP.recNo
  4278.    AP.recPtr
  4279.    AP.keyPtr
  4280.  
  4281.  Retrieve the key for the record/record number pair. 
  4282.  
  4283.  This routine would typically be used prior to using DELETE_KEY_XB and 
  4284.  DEBUMP_RECORD_XB.  The key returned includes the enumerator if applicable. 
  4285.  This routine sifts through any duplicate keys (if DUPS_ALLOWED) for the key 
  4286.  that matches the record/record number pair, and so requires both the actual 
  4287.  data record along with its physical record number (even if dups are not 
  4288.  allowed). 
  4289.  
  4290.  Typically this routine is extraneous; the key is available with a GET_XB 
  4291.  routine and so can be deleted from the information provided through normal 
  4292.  access. 
  4293.  
  4294.  This routine builds a key based on the supplied record at AP.recPtr and 
  4295.  searches the index for that key proper.  If found, and if DUPS_ALLOWED, each 
  4296.  key matching the key proper has its record number compared to the record 
  4297.  number in AP.recNo.  If that matches, too, then that is the exact key being 
  4298.  sought. 
  4299.  
  4300.  
  4301. ΓòÉΓòÉΓòÉ 9.51. GET_FIRST_XB ΓòÉΓòÉΓòÉ
  4302.  
  4303. Pack: ACCESSPACK               Source Example 
  4304.  
  4305.      IN               OUT
  4306.    AP.func          AP.stat
  4307.    AP.handle        AP.recNo
  4308.    AP.recPtr        *AP.recPtr
  4309.    AP.keyPtr        *AP.keyPtr
  4310.  
  4311.  Retrieve the first indexed key and its data record. 
  4312.  
  4313.  The key returned includes an enumerator if the index file uses non-unique keys 
  4314.  (DUPS_ALLOWED). 
  4315.  
  4316.  This routine is typically used to process a database in index order starting 
  4317.  at the first ordered key (and its data record).  After processing this first 
  4318.  entry, subsequent in-order access of the database is achieved by using 
  4319.  GET_NEXT_XB, until the end of the database is reached, at which point an error 
  4320.  is returned. 
  4321.  
  4322.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4323.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4324.  number pointed to by the first key. Since this is done upon each GET_XB 
  4325.  access, the AP pack is primed for an UPDATE_XB 
  4326.  
  4327.  
  4328. ΓòÉΓòÉΓòÉ 9.52. GET_EQUAL_XB ΓòÉΓòÉΓòÉ
  4329.  
  4330. Pack: ACCESSPACK               Source Example 
  4331.  
  4332.      IN               OUT
  4333.    AP.func          AP.stat
  4334.    AP.handle        AP.recNo
  4335.    AP.recPtr        *AP.recPtr
  4336.    AP.keyPtr
  4337.  
  4338.  Search for the exact key in the index file and return its data record. 
  4339.  
  4340.  This routine finds only an exact match to the specified key (including the 
  4341.  enumerator if applicable).  However, even if the exact key is not found in the 
  4342.  index file, the index file is positioned so that the next GET_NEXT_XB 
  4343.  retrieves the key that would have followed the unmatched specified key.  In 
  4344.  this manner, a GET_GREATER_THAN_OR_EQUAL is easily performed.  See also 
  4345.  EQUAL_KEY_XB. 
  4346.  
  4347.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4348.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4349.  number pointed to by the matching key. Since this is done upon each GET_XB 
  4350.  access, the AP pack is primed for an UPDATE_XB 
  4351.  
  4352.  Note:  When using the partial key technique as described in EQUAL_KEY_XB, be 
  4353.  sure to set the unspecified characters of the key to \0, or at least the two 
  4354.  bytes immediately following your search criterion.  This for both unique and 
  4355.  non-unique index files. 
  4356.  
  4357.  
  4358. ΓòÉΓòÉΓòÉ 9.53. GET_NEXT_XB ΓòÉΓòÉΓòÉ
  4359.  
  4360. Pack: ACCESSPACK               Source Example 
  4361.  
  4362.      IN               OUT
  4363.    AP.func          AP.stat
  4364.    AP.handle        AP.recNo
  4365.    AP.recPtr        *AP.recPtr
  4366.    AP.keyPtr        *AP.keyPtr
  4367.  
  4368.  Retrieve the next indexed key and its data record. 
  4369.  
  4370.  The key returned includes an enumerator if the index file uses non-unique keys 
  4371.  (DUPS_ALLOWED). 
  4372.  
  4373.  This routine is typically called after the index file has first been 
  4374.  positioned to a known key using either GET_FIRST_XB or GET_EQUAL_XB, or after 
  4375.  a previous GET_NEXT_XB or even GET_PREV_XB.  What it basically does is get the 
  4376.  key and data record following the current key, and then makes that key the new 
  4377.  current key. 
  4378.  
  4379.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4380.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4381.  number pointed to by the next key (now the current key). Since this is done 
  4382.  upon each GET_XB access, the AP pack is primed for an UPDATE_XB. ________________________________________________
  4383.  
  4384.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4385.  based on a given starting point.  This simplifies index access in 
  4386.  multi-threaded code, where another thread may have altered the last key 
  4387.  accessed in the index file.  This mode lets you set a starting point for the 
  4388.  operation by supplying in AP.keyPtr the key value to start at. 
  4389.  
  4390.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4391.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4392.  accesses that same index file handle, and performs some other access, where 
  4393.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4394.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4395.  however, it very likely won't since the second thread has altered the last 
  4396.  accessed key for that file handle.  By using the atomic mode for key access, 
  4397.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4398.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4399.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4400.  operation.  This is performed within the Bullet kernel, and so won't be 
  4401.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4402.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4403.  accessed key.  This will always be the case unless uninitialized, or you are 
  4404.  using global variables for your threads' AP (AccessPack).  On return from the 
  4405.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4406.  
  4407.  Note:  You must supply a valid key value for this atomic access mode. 
  4408.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4409.  have the starting point for the operation (i.e., the last accessed key).  You 
  4410.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4411.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4412.  reverts to the internally-stored last key accessed as the starting point. 
  4413.  
  4414.  
  4415. ΓòÉΓòÉΓòÉ 9.54. GET_PREV_XB ΓòÉΓòÉΓòÉ
  4416.  
  4417. Pack: ACCESSPACK               Source Example 
  4418.  
  4419.      IN               OUT
  4420.    AP.func          AP.stat
  4421.    AP.handle        AP.recNo
  4422.    AP.recPtr        *AP.recPtr
  4423.    AP.keyPtr        *AP.keyPtr
  4424.  
  4425.  Retrieve the previous indexed key and its data record. 
  4426.  
  4427.  The key returned includes an enumerator if the index file uses non-unique keys 
  4428.  (DUPS_ALLOWED). 
  4429.  
  4430.  This routine is typically called after the index file has first been 
  4431.  positioned to a known key using either GET_LAST_XB or GET_EQUAL_XB, or after a 
  4432.  previous GET_PREV_XB or even GET_NEXT_XB.  What it basically does is get the 
  4433.  key and data record preceding the current key, and then makes that key the new 
  4434.  current key. 
  4435.  
  4436.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4437.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4438.  number pointed to by the previous key (now the current key). Since this is 
  4439.  done upon each GET_XB access, the AP pack is primed for an UPDATE_XB. ________________________________________________
  4440.  
  4441.  If bit0 of the atomic mode flag of SET_SYSVARS_XB is set to 1, key access is 
  4442.  based on a given starting point.  This simplifies index access in 
  4443.  multi-threaded code, where another thread may have altered the last key 
  4444.  accessed in the index file.  This mode lets you set a starting point for the 
  4445.  operation by supplying in AP.keyPtr the key value to start at. 
  4446.  
  4447.  For example, say you use GET_FIRST_XB.  On return, AP.keyPtr has the the very 
  4448.  first key.  Say elsewhere in your multi-threaded program, another operation 
  4449.  accesses that same index file handle, and performs some other access, where 
  4450.  the last accessed key is no longer the same (i.e., not the first key).  Your 
  4451.  first thread is expecting that a GET_NEXT_XB would get the second key, 
  4452.  however, it very likely won't since the second thread has altered the last 
  4453.  accessed key for that file handle.  By using the atomic mode for key access, 
  4454.  your first thread, which has the first key value in its AP.keyPtr, can do a 
  4455.  call to GET_NEXT_XB and get expected results, since the NEXT operation first 
  4456.  positions to the value in AP.keyPtr and then follows up with a GET_NEXT 
  4457.  operation.  This is performed within the Bullet kernel, and so won't be 
  4458.  interrupted by another thread (i.e., it is an atomic operation).  For this to 
  4459.  work, you must ensure that the AP.keyPtr value is set to the value of the last 
  4460.  accessed key.  This will always be the case unless uninitialized, or you are 
  4461.  using global variables for your threads' AP (AccessPack).  On return from the 
  4462.  operation, AP.keyPtr will once again be set up for another atomic operation. 
  4463.  
  4464.  Note:  You must supply a valid key value for this atomic access mode. 
  4465.  AP.keyPtr must be at least as large as the key length in all cases, and is to 
  4466.  have the starting point for the operation (i.e., the last accessed key).  You 
  4467.  may, alternatively, set the first byte of the key buffer to 0 (but not 
  4468.  AP.keyPtr itself to NULL).  This disables atomic mode for that access, and 
  4469.  reverts to the internally-stored last key accessed as the starting point. 
  4470.  
  4471.  
  4472. ΓòÉΓòÉΓòÉ 9.55. GET_LAST_XB ΓòÉΓòÉΓòÉ
  4473.  
  4474. Pack: ACCESSPACK               Source Example 
  4475.  
  4476.      IN               OUT
  4477.    AP.func          AP.stat
  4478.    AP.handle        AP.recNo
  4479.    AP.recPtr        *AP.recPtr
  4480.    AP.keyPtr        *AP.keyPtr
  4481.  
  4482.  Retrieve the last indexed key and its data record. 
  4483.  
  4484.  The key returned includes an enumerator if the index file uses non-unique keys 
  4485.  (DUPS_ALLOWED). 
  4486.  
  4487.  This routine is typically used to process a database in reverse index order 
  4488.  starting at the last ordered key (and its data record).  After processing this 
  4489.  last entry, subsequent reverse-order access of the database is achieved by 
  4490.  using GET_PREV_XB, until the top of the database is reached, at which point an 
  4491.  error is returned. 
  4492.  
  4493.  This routine, like all the high-level GET_XB routines, fills in the AP.recNo 
  4494.  of the record accessed.  In this case, it fills AP.recNo with the record 
  4495.  number pointed to by the last key. Since this is done upon each GET_XB access, 
  4496.  the AP pack is primed for an UPDATE_XB 
  4497.  
  4498.  
  4499. ΓòÉΓòÉΓòÉ 9.56. INSERT_XB ΓòÉΓòÉΓòÉ
  4500.  
  4501. Pack: ACCESSPACK               Source Example 
  4502.  
  4503.      IN               OUT
  4504.    AP.func          AP.stat
  4505.    AP.handle        AP.recNo
  4506.    AP.recNo         *AP.keyPtr
  4507.    AP.recPtr
  4508.    AP.keyPtr
  4509.    AP.nextPtr
  4510.  
  4511.  Append the data records to data files and build and insert the related keys 
  4512.  into all linked index files.  (Alternate forms are possible.) 
  4513.  
  4514.  This routine is used to add new entries into a database.  Up to 256 index 
  4515.  files may be inserted into per call, with up to 256 data files being added, 
  4516.  too, for a total of 512 files managed per single INSERT_XB call. 
  4517.  
  4518.  Note:  Bullet comes in 100, 250, and 1024-file versions and so this routine is 
  4519.  able to use as many files as handles are still available. If non-standard 
  4520.  fields are used (i.e., non-char structure members to match non-ASCII data 
  4521.  fields in your non-standard DBF), then be aware that your compiler more than 
  4522.  likely will add padding to align on member-size boundaries.  This will result 
  4523.  in a mis-match between your compiler structure (rectype above) and your DBF 
  4524.  structure (as described in fieldList[]).  To prevent this, place #pragma 
  4525.  pack(1) / #pragma pack() around your structures that BULLET uses.  Consult 
  4526.  your particular compiler for alternate methods if it does not support #pragma 
  4527.  pack. 
  4528.  
  4529.  Only index handles are listed in AP.handle.  Each index file has associated 
  4530.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  4531.  There may be more than one index file for a data file, but there is always one 
  4532.  data file per index handle specified in the list.  In other words, you can 
  4533.  list five index files, each indexing the same xbLink data file, and have 
  4534.  BULLET perform an atomic insert of that list.  Or, another possibility is that 
  4535.  you have a single index file, indexing a single data file.  Or, you can list 
  4536.  256 index files, each indexing a single data file (512 total files). 
  4537.  
  4538.  This, and several other routines, are transaction-list-based.  This means that 
  4539.  if a failure occurs prior to the routine's completion, all changes made to the 
  4540.  database by the routine will be backed-out, and the database (data and index 
  4541.  files) effectively restored to its original state. 
  4542.  
  4543.  If the routine failed to complete, the function return value is the number 
  4544.  (1-based) of the pack that caused the failure.  A positive number indicates 
  4545.  the failure was from an index operation; a negative number indicates the 
  4546.  failure was from a data operation.  In each case, the absolute value of the 
  4547.  return code is the list item that failed (the pack index).  For example, if 
  4548.  five index handles are in the list (AP[0] to AP[4]), and an error occurred on 
  4549.  the last pack's index file, the return code would be positive 5, indicating 
  4550.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  4551.  being processed when the error occurred.  Being processed means not only 
  4552.  physical access, but verification, etc.  If the return code was -5, then 
  4553.  again, the error was in the fifth pack, but since it is negative, the error 
  4554.  occurred while processing the data file.  In either case, upon return, the 
  4555.  database is effectively restored to the way it was before the INSERT_XB call 
  4556.  was made.  Remedy the error, if possible, and INSERT_XB again. 
  4557.  
  4558.  Each pack must include a separate key buffer.  You must not share a common key 
  4559.  buffer.  Doing so disables any chance of recovering the index files in case of 
  4560.  error, since it is in these buffers that BULLET places the newly built keys, 
  4561.  and it is from these that BULLET, upon an error condition, deletes the keys 
  4562.  (required for roll-back). 
  4563.  
  4564.  The enumerator is automatically set up by this routine, if required 
  4565.  (DUPS_ALLOWED and the key already exists with enumerator 0).  It does this by 
  4566.  seeking the last possible enumerator value (0xFFFF) and then backing up to the 
  4567.  previous key.  That key's enumerator is evaluated and incremented, and used as 
  4568.  this key's. 
  4569.  
  4570.  Specifying Files 
  4571.  
  4572.  As mentioned, only the index file handles are specified in AP.handle. Data 
  4573.  files are implicitly specified by their links to the index files, as specified 
  4574.  when the index file was opened (OP.xbLink).  INSERT_XB can process up to 256 
  4575.  index files per call.  Since each index file requires a data file, this means 
  4576.  that up to 256 data files can be processed per call, as well.  Also possible 
  4577.  is that all 256 index handles refer to the same, single data file.  Yet 
  4578.  another possibility is that there is 1 index file, and so 1 data file.  The 
  4579.  possibilities can include those and anything in between. 
  4580.  
  4581.  Example: Specifying a single index file 
  4582.  
  4583.  The simplest form is where a single index handle is specified.  This implies a 
  4584.  single data file, too.  AccessPack setup for this is: 
  4585.  
  4586.   AP.func = INSERT_XB;
  4587.   AP.handle = indexHandle;
  4588.   AP.recNo = 0;
  4589.   AP.recPtr = &recordStruct; // contents referred to below as *recordStruct
  4590.   AP.keyPtr = keyBuffer;
  4591.   AP.nextPtr = NULL;
  4592.  
  4593.  A call to BULLET with the above does the following: 
  4594.  
  4595.    1. The data in *recordStruct is used as a new record that is appended to the 
  4596.       data file.  The data file was linked to this index during the index open, 
  4597.       in OP.xbLink. 
  4598.  
  4599.    2. A key is built by BULLET, based on the data in *recordStruct, and that 
  4600.       key is inserted into the index file (AP.handle).  Stored with the key is 
  4601.       the record number of the record added above. 
  4602.  
  4603.  Note:  AP.recNo must be set to 0 prior to the call.  Any positive number 
  4604.  results in an error (0x80000000, and negative numbers, may be used when more 
  4605.  than one AP pack is used - see below). 
  4606.  
  4607.  Upon return, if no error, the return code is 0.  AP.recNo is set to the 
  4608.  physical record number in the data file that *recordStruct was placed.  The 
  4609.  key that was stored, including any enumerator, is in *keyBuffer. 
  4610.  
  4611.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  4612.  the error was caused during processing of the data file portion, and the error 
  4613.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  4614.  the index file, and the error code itself is in AP.stat, as well.  The return 
  4615.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  4616.  that generated the error -- negative if a data file error, positive if an 
  4617.  index file error.  Since this example has only the single pack, only a -1 or 
  4618.  +1 could be returned, or 0. 
  4619.  
  4620.  Note:  If an error occurred after any part of the database had changed (during 
  4621.  this particular call), then any and all changes that were made are backed-out, 
  4622.  and the files restored to the same state as before the call. 
  4623.  
  4624.  Example: Specifying two index files for a single data file 
  4625.  
  4626.  Two index files, related to the same data file, would set AccessPack to: 
  4627.  
  4628.   AP[0].func = INSERT_XB;
  4629.   AP[0].handle = indexHandle_0;
  4630.   AP[0].recNo = 0;
  4631.   AP[0].recPtr = &recordStruct;
  4632.   AP[0].keyPtr = keyBuffer_0;
  4633.   AP[0].nextPtr = AP[1];
  4634.  
  4635.   AP[1].handle = indexHandle_1;
  4636.   AP[1].recNo = 0x80000000;
  4637.   AP[1].recPtr = &recordStruct;
  4638.   AP[1].keyPtr = keyBuffer_1;
  4639.   AP[1].nextPtr = NULL;
  4640.  
  4641.  A call to BULLET with the above does the following: 
  4642.  
  4643.    1. The data in *recordStruct is used as a new record that is appended 
  4644.       (added) to the data file. 
  4645.  
  4646.    2. A key is built by BULLET, based on the data in *recordStruct, and that 
  4647.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  4648.       is the record number of the record added above. 
  4649.  
  4650.    3. A second key is built by BULLET, based on the data in *recordStruct, and 
  4651.       that key is inserted into the second index file (AP[1].handle).  Stored 
  4652.       with the key is the record number of the record added above. 
  4653.  
  4654.  Note:  The 0x80000000 in AP[1].recNo signifies that AP[1] is using the same 
  4655.  data record that was appended during processing of AP[0].  This results in 
  4656.  just the one data record being added.  AP[1].recPtr must still, however, point 
  4657.  to the same data as AP[0].recPtr does. 
  4658.  
  4659.  Upon return, if no error, the return code is 0.  AP[0].recNo is set to the 
  4660.  physical record number in the data file that *recordStruct was placed.  The 
  4661.  key that was stored for the first index, including any enumerator, is in the 
  4662.  buffer at AP[0].keyPtr.  AP[1].recNo is set to the same physical record number 
  4663.  as AP[0].recNo, except that the record number is negative: For example, if 
  4664.  AP[0].recNo is 22 on return, AP[1].recNo is -22 (the original 0x80000000 value 
  4665.  is overwritten).  The key that was stored for the second index, including any 
  4666.  enumerator, is in the buffer at AP[1].keyPtr. 
  4667.  
  4668.  Upon return, and there was an error, the return code can be -2, -1, 1, or 2. 
  4669.  If negative, the error was caused during processing of that AP pack's data 
  4670.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  4671.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  4672.  positive, the error was caused during processing of that AP pack's index file, 
  4673.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  4674.  as in all BULLET transaction-list routines, an index of the AP pack that 
  4675.  generated the error -- negative if a data file error, positive if an index 
  4676.  file error. 
  4677.  
  4678.  Note:  If an error occurred after any part of the database had changed (during 
  4679.  this particular call), then any and all changes that were made are backed-out, 
  4680.  and the files restored to the same state as before the call. 
  4681.  
  4682.  Example: Specifying two index files for each of two different data files 
  4683.  
  4684.  Four total files: two index files related to one data file, and two other 
  4685.  index files related to another data file, would set AccessPack to: 
  4686.  
  4687.   AP[0].func = INSERT_XB;
  4688.   AP[0].handle = indexHandle_0;
  4689.   AP[0].recNo = 0;
  4690.   AP[0].recPtr = &recordStruct_0;
  4691.   AP[0].keyPtr = keyBuffer_0;
  4692.   AP[0].nextPtr = AP[1];
  4693.  
  4694.   AP[1].handle = indexHandle_1;
  4695.   AP[1].recNo = 0x80000000;
  4696.   AP[1].recPtr = &recordStruct_0;
  4697.   AP[1].keyPtr = keyBuffer_1;
  4698.   AP[1].nextPtr = AP[2];
  4699.  
  4700.   AP[2].handle = indexHandle_2;
  4701.   AP[2].recNo = 0;
  4702.   AP[2].recPtr = &recordStruct_1;
  4703.   AP[2].keyPtr = keyBuffer_2;
  4704.   AP[2].nextPtr = AP[3];
  4705.  
  4706.   AP[3].handle = indexHandle_3;
  4707.   AP[3].recNo = 0x80000000;
  4708.   AP[3].recPtr = &recordStruct_1;
  4709.   AP[3].keyPtr = keyBuffer_3;
  4710.   AP[3].nextPtr = NULL;
  4711.  
  4712.  A call to BULLET with the above does the following: 
  4713.  
  4714.    1. The data in *recordStruct_0 is used as a new record that is appended to 
  4715.       the data file linked to the index file in AP[0].handle. 
  4716.  
  4717.    2. A key is built by BULLET, based on the data in *recordStruct_0, and that 
  4718.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  4719.       is the record number of the record added above, for _0. 
  4720.  
  4721.    3. A second key is built by BULLET, based on the data in *recordStruct_0, 
  4722.       and that key is inserted into the second index file (AP[1].handle). 
  4723.       Stored with the key is the record number of the record added above, using 
  4724.       *recordStruct_0. 
  4725.  
  4726.    4. The data in *recordStruct_1 is used as a new record that is appended to 
  4727.       the data file linked to the index file in AP[2].handle. 
  4728.  
  4729.    5. A third key is built by BULLET, based on the data in *recordStruct_1, and 
  4730.       that key is inserted into the index file (AP[2].handle).  Stored with the 
  4731.       key is the record number of the record added above, for _1. 
  4732.  
  4733.    6. A fourth key is built by BULLET, based on the data in *recordStruct_1, 
  4734.       and that key is inserted into the fourth index file (AP[3].handle). 
  4735.       Stored with the key is the record number of the record added above, using 
  4736.       *recordStruct_1. 
  4737.  
  4738.  Note:  The 0x80000000 in AP[1].recNo signifies that AP[1] is using the same 
  4739.  data record that was appended during processing of AP[0].  This results in 
  4740.  just the one data record being added.  AP[1].recPtr must still, however, point 
  4741.  to the same data as AP[0].recPtr does.  The same applies to AP[2] and AP[3] 
  4742.  (though different values, of course). 
  4743.  
  4744.  Upon return, if no error, the return code is 0.  AP[0].recNo is set to the 
  4745.  physical record number in the data file that *recordStruct_0 was placed. The 
  4746.  key that was stored for the first index, including any enumerator, is in the 
  4747.  buffer at AP[0].keyPtr.  AP[1].recNo is set to the same physical record number 
  4748.  as AP[0].recNo, except that the record number is negative: For example, if 
  4749.  AP[0].recNo is 22 on return, AP[1].recNo is -22 (the original 0x80000000 value 
  4750.  is overwritten).  The key that was stored for the second index, including any 
  4751.  enumerator, is in the buffer at AP[1].keyPtr.  AP[2].recNo is set to the 
  4752.  physical record number in the data file that *recordStruct_1 was placed.  The 
  4753.  key that was stored for the third index, including any enumerator, is in the 
  4754.  buffer at AP[2].keyPtr.  AP[3].recNo is set to the same physical record number 
  4755.  as AP[2].recNo, except that the record number is negative: For example, if 
  4756.  AP[2].recNo is 74 on return, AP[3].recNo is -74 (the original 0x80000000 value 
  4757.  is overwritten).  The key that was stored for the fourth index, including any 
  4758.  enumerator, is in the buffer at AP[3].keyPtr. 
  4759.  
  4760.  Upon return, and there was an error, the return code can be -4 to -1, or 1 to 
  4761.  4.  If negative, the error was caused during processing of that AP pack's data 
  4762.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  4763.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  4764.  positive, the error was caused during processing of that AP pack's index file, 
  4765.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  4766.  as in all BULLET transaction-list routines, an index of the AP pack that 
  4767.  generated the error -- negative if a data file error, positive if an index 
  4768.  file error. 
  4769.  
  4770.  Note:  If an error occurred after any part of the database had changed (during 
  4771.  this particular call), then any and all changes that were made are backed-out, 
  4772.  and the files restored to the same state as before the call. 
  4773.  
  4774.  Example: Specifying two index files for two records in the same data file 
  4775.  
  4776.  Three files: two index files related to one data file, where two data records 
  4777.  are to be appended, would set AccessPack to: 
  4778.  
  4779.   AP[0].func = INSERT_XB;
  4780.   AP[0].handle = indexHandle_0;
  4781.   AP[0].recNo = 0;
  4782.   AP[0].recPtr = &recordStruct_0;
  4783.   AP[0].keyPtr = keyBuffer_0;
  4784.   AP[0].nextPtr = AP[1];
  4785.  
  4786.   AP[1].handle = indexHandle_1;
  4787.   AP[1].recNo = 0x80000000;
  4788.   AP[1].recPtr = &recordStruct_0;
  4789.   AP[1].keyPtr = keyBuffer_1;
  4790.   AP[1].nextPtr = AP[2];
  4791.  
  4792.   AP[2].handle = indexHandle_0;
  4793.   AP[2].recNo = 0;
  4794.   AP[2].recPtr = &recordStruct_1;
  4795.   AP[2].keyPtr = keyBuffer_2;
  4796.   AP[2].nextPtr = AP[3];
  4797.  
  4798.   AP[3].handle = indexHandle_1;
  4799.   AP[3].recNo = 0x80000000;
  4800.   AP[3].recPtr = &recordStruct_1;
  4801.   AP[3].keyPtr = keyBuffer_3;
  4802.   AP[3].nextPtr = NULL;
  4803.  
  4804.  A call to BULLET with the above does the following: 
  4805.  
  4806.    1. The data in *recordStruct_0 is used as a new record that is appended to 
  4807.       the data file linked to the index file in AP[0].handle. 
  4808.  
  4809.    2. A key is built by BULLET, based on the data in *recordStruct_0, and that 
  4810.       key is inserted into the index file (AP[0].handle).  Stored with the key 
  4811.       is the record number of the record added above, for _0. 
  4812.  
  4813.    3. A second key is built by BULLET, based on the data in *recordStruct_0, 
  4814.       and that key is inserted into the second index file (AP[1].handle). 
  4815.       Stored with the key is the record number of the record added above, using 
  4816.       *recordStruct_0. 
  4817.  
  4818.    4. The data in *recordStruct_1 is used as a new record that is appended to 
  4819.       the data file linked to the index file in AP[2].handle.  Since 
  4820.       AP[2].handle is the same index file as that of AP[0].handle, this means 
  4821.       it's also the same data file as was just operated on above -- a second 
  4822.       data record is appended to the data file.  The net effect of this 
  4823.       operation is to call INSERT_XB twice, once for one insert, then again for 
  4824.       the second.  The difference is that the operation is atomic -- if one 
  4825.       fails, the other is not committed; it's an "all or nothing" operation. 
  4826.  
  4827.    5. A third key is built by BULLET, based on the data in *recordStruct_1, and 
  4828.       that key is inserted into the index file (AP[2].handle).  Stored with the 
  4829.       key is the record number of the record added directly above, for _1. Note 
  4830.       that this index file is the same as specified in AP[0].handle. 
  4831.  
  4832.    6. A fourth key is built by BULLET, based on the data in *recordStruct_1, 
  4833.       and that key is inserted into the fourth index file (AP[3].handle). 
  4834.       Stored with the key is the record number of the record added above, using 
  4835.       *recordStruct_1. 
  4836.  The return ritual is as described above, for "Specifying two index files each 
  4837.  for two different data files". 
  4838.  
  4839.  Example: Specifying a single index file for a previously added data record 
  4840.  
  4841.  This form lets you insert a key without adding a data record.  This would be 
  4842.  required if you were, for example, creating a temporary index of select 
  4843.  records in a data file (i.e., the data records already exist, you just want to 
  4844.  index them).  AccessPack setup for this is: 
  4845.  
  4846.   AP.func = INSERT_XB;
  4847.   AP.handle = indexHandle;
  4848.   AP.recNo = -recordNumberOfExistingRecord;
  4849.   AP.recPtr = &recordStruct;
  4850.   AP.keyPtr = keyBuffer;
  4851.   AP.nextPtr = NULL;
  4852.  
  4853.  A call to BULLET with the above does the following: 
  4854.  
  4855.    1. A key is built by BULLET, based on the data in *recordStruct, and that 
  4856.       key is inserted into the index file (AP.handle).  Stored with the key is 
  4857.       the absolute value of the record number specified in AP.recNo (which is 
  4858.       set to negative record number). 
  4859.  
  4860.  Upon return, if no error, the return code is 0.  AP.recNo is changed to 
  4861.  abs(AP.recNo).  The key that was stored, including any enumerator, is in 
  4862.  *keyBuffer.  No data file access is made. 
  4863.  
  4864.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  4865.  the error was caused during processing of the data file portion, and the error 
  4866.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  4867.  the index file, and the error code itself is in AP.stat, as well.  The return 
  4868.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  4869.  that generated the error -- negative if a data file error, positive if an 
  4870.  index file error.  Since this example has only the single pack, only a -1 or 
  4871.  +1 could be returned. 
  4872.  
  4873.  Note:  If an error occurred after any part of the database had changed (during 
  4874.  this particular call), then any and all changes that were made are backed-out, 
  4875.  and the files restored to the same state as before the call. 
  4876.  
  4877.  An example use of this INSERT_XB feature is to create an ad hoc index of, say, 
  4878.  records marked as deleted.  To do this, create a new index file (say, with a 
  4879.  key of NAME).  Get each data record, by record number using GET_RECORD_XB (for 
  4880.  records 1 to number-of-records), and check the .tag byte.  If '*', call 
  4881.  INSERT_XB with the negative value of AP.recNo.  Do this for every such marked 
  4882.  record.  After all records are processed, you have an index of all deleted 
  4883.  records in the data file.  Delete the index when no longer needed.  That's 
  4884.  just one example. 
  4885.  
  4886.  
  4887. ΓòÉΓòÉΓòÉ 9.57. UPDATE_XB ΓòÉΓòÉΓòÉ
  4888.  
  4889. Pack: ACCESSPACK               Source Example 
  4890.  
  4891.      IN               OUT
  4892.    AP.func          AP.stat
  4893.    AP.handle        *AP.keyPtr
  4894.    AP.recNo
  4895.    AP.recPtr
  4896.    AP.keyPtr
  4897.    AP.nextPtr
  4898.  
  4899.  Update any and all files in the transaction list if necessary, including both 
  4900.  index and data files. 
  4901.  
  4902.  This routine is used to update data records while also updating the index 
  4903.  files if a key field has changed due to data record updates.  Up to 256 index 
  4904.  files may be updated per call, as well as 256 data files, too, for a total of 
  4905.  512 files managed per single UPDATE_XB call. 
  4906.  
  4907.  Only index handles are listed in AP.handle.  Each index file has associated 
  4908.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  4909.  There may be more than one index file for a data file, but there is always one 
  4910.  data file per index handle specified in the list.  In other words, you can 
  4911.  list five index files, each indexing the same xbLink data file, and have 
  4912.  BULLET perform an atomic update of that list. Or, another possibility is that 
  4913.  you have a single index file, indexing a single data file.  Or, you can list 
  4914.  256 index files, each indexing a single data file (512 total files). 
  4915.  
  4916.  This, and several other routines, are transaction-list-based.  This means that 
  4917.  if a failure occurs prior to the routine's completion, all changes made to the 
  4918.  database by the routine will be backed-out, and the database (data and index 
  4919.  files) effectively restored to its original state. 
  4920.  
  4921.  If the routine failed to complete, the function return value is the number 
  4922.  (1-based) of the pack that caused the failure.  A positive number indicates 
  4923.  the failure was from an index operation; a negative number indicates the 
  4924.  failure was from a data operation.  In each case, the absolute value of the 
  4925.  return code is the list item that failed (the pack index).  For example, if 
  4926.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  4927.  the last pack's index file, the return code would be positive 5, indicating 
  4928.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  4929.  being processed when the error occurred.  Being processed means not only 
  4930.  physical access, but verification, etc.  If the return code was -5, then 
  4931.  again, the error was in the fifth pack, but since it is negative, the error 
  4932.  occurred while processing the data file.  In either case, upon return, the 
  4933.  database is restored to the way it was before the UPDATE_XB call was made. 
  4934.  Remedy the error, if possible, and UPDATE_XB again. 
  4935.  
  4936.  Each pack must include a separate key buffer.  You must not share a common key 
  4937.  buffer.  Doing so disables any chance of recovering the index files in case of 
  4938.  error, since it is in these buffers that BULLET places any newly built keys, 
  4939.  and it is from these that BULLET, upon an error condition, deletes these keys 
  4940.  (required for roll-back). 
  4941.  
  4942.  The enumerator is automatically maintained by this routine, if required 
  4943.  (DUPS_ALLOWED and the key already exists with enumerator 0).  The process is 
  4944.  the same as INSERT_XB's. 
  4945.  
  4946.  How an update works 
  4947.  
  4948.  All data records specified in the list are read from disk into memory, except 
  4949.  those with AP.recNo=0.  Therefore, a memory allocation large enough to store 
  4950.  all unique data records is made upon entry to this routine (and released at 
  4951.  exit).  For example, if the list includes two implicit data files, and the 
  4952.  record lengths of those two data files are 2048 and 4096 bytes, an allocation 
  4953.  of 6K is made.  In addition, 40KB more is allocated for workspace.  So, for 
  4954.  this example, 46K is allocated (rounded up to 48KB, the next 4KB page 
  4955.  boundary).  Since up to 256 unique records are possible, where a unique record 
  4956.  is identified by handle/record number, be aware of the memory requirements if 
  4957.  you are updating very large databases (e.g., 256 unique records, each 4KB in 
  4958.  length, would have UPDATE_XB allocate a bit over 1MB of memory for this call). 
  4959.  
  4960.  After the data records have been read from disk, each list-item is processed, 
  4961.  in order.  The disk record image previously read is compared with the record 
  4962.  image at AP.recPtr.  If the same, that item is skipped, and the next item in 
  4963.  the list is processed.  If you know beforehand that that record is the same, 
  4964.  set that item's AP.recNo=0 so you can avoid having its disk image read and 
  4965.  stored (or do not include it in the list at all).  If the images differ, 
  4966.  BULLET creates a key for the index file being processed, for each record image 
  4967.  (the original and the one in AP.recPtr).  If the keys generated are the same, 
  4968.  no index file update is needed.  If different, the original key for that 
  4969.  record is deleted from that index file, and the new key inserted. Finally, the 
  4970.  new record replaces the old, the new directly overwriting the original.  Note 
  4971.  that the actual sequence of the update event differs somewhat from this 
  4972.  description in order to optimize the process. 
  4973.  
  4974.  Specifying Files 
  4975.  
  4976.  As mentioned, only the index file handles are specified in AP.handle. Data 
  4977.  files are implicitly specified by their links to the index files, as specified 
  4978.  when the index file was opened (OP.xbLink).  UPDATE_XB can process up to 256 
  4979.  index files per call.  Since each index file requires a data file, this means 
  4980.  that up to 256 data files can be processed per call as well.  Also possible is 
  4981.  that all 256 index handles refer to the same, single data file.  Yet another 
  4982.  possibility is that there is 1 index file, and so 1 data file.  The 
  4983.  possibilities can include those and anything in between. 
  4984.  
  4985.  Example: Specifying a single index file 
  4986.  
  4987.  The simplest form is where a single index handle is specified.  This implies a 
  4988.  single data file, too.  AccessPack setup for this is: 
  4989.  
  4990.   AP.func = UPDATE_XB;
  4991.   AP.handle = indexHandle;
  4992.   AP.recNo = recordToUpdate;
  4993.   AP.recPtr = &recordStruct;
  4994.   AP.keyPtr = keyBuffer;
  4995.   AP.nextPtr = NULL;
  4996.  
  4997.  A call to BULLET with the above does the following: 
  4998.  
  4999.    1. The data in *recordStruct is used as the new record that is to replace 
  5000.       the data record at AP.recNo.  The data file was linked to this index file 
  5001.       (AP.handle) during the index open, in OP.xbLink. 
  5002.  
  5003.    2. If the record data in *recordStruct is the same as the original disk 
  5004.       record, nothing is done.  If the data is new, the key fields are compared 
  5005.       to that belonging to the original disk record, and if the same, only the 
  5006.       record data is updated.  If the new record's key differs from the 
  5007.       original's, the original key for this record is removed from the index, 
  5008.       and the new key inserted. 
  5009.  
  5010.  AP.recNo must be set to the record number that you are updating. Any GET_XB 
  5011.  routine (GET_EQUAL_XB, etc.) may be used to identify the number of a data 
  5012.  record.  Key access has the obvious advantage of knowing the record number of 
  5013.  a specific key (for example, Betty Barbar's data). Any record number, from 1 
  5014.  to number of records in the data file, can be used.  In addition, a negative 
  5015.  record number can be used.  This is treated exactly the same as a positive 
  5016.  record number (the absolute value is used). The reason this is allowed is 
  5017.  because INSERT_XB replaces 0x80000000 record numbers with the negative value 
  5018.  of the previous insert. 
  5019.  
  5020.  Upon return, if no error, the return code is 0.  If the record data was new, 
  5021.  the key for that data record, including any enumerator, is in *keyBuffer. 
  5022.  This is so even if key fields had not changed. 
  5023.  
  5024.  Upon return, and there was an error, the return code is either -1 or 1. If -1, 
  5025.  the error was caused during processing of the data file portion, and the error 
  5026.  code itself is in AP.stat.  If +1, the error was caused during processing of 
  5027.  the index file, and the error code itself is in AP.stat, as well.  The return 
  5028.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5029.  that generated the error -- negative if a data file error, positive if an 
  5030.  index file error.  Since this example has only the single pack, only a -1 or 
  5031.  +1 could be returned. 
  5032.  
  5033.  Note:  If an error occurred after any part of the database had changed (during 
  5034.  this particular call), then any and all changes that were made are backed-out, 
  5035.  and the files restored to the same state as before the call. 
  5036.  
  5037.  Example: Specifying two index files for a single data file 
  5038.  
  5039.  Two index files, related to the same data file, would set AccessPack to: 
  5040.  
  5041.   AP[0].func = UPDATE_XB;
  5042.   AP[0].handle = indexHandle_0;
  5043.   AP[0].recNo = recordToUpdate;
  5044.   AP[0].recPtr = &recordStruct;
  5045.   AP[0].keyPtr = keyBuffer_0;
  5046.   AP[0].nextPtr = AP[1];
  5047.  
  5048.   AP[1].handle = indexHandle_1;
  5049.   AP[1].recNo = recordToUpdate;
  5050.   AP[1].recPtr = &recordStruct;
  5051.   AP[1].keyPtr = keyBuffer_1;
  5052.   AP[1].nextPtr = NULL;
  5053.  
  5054.  A call to BULLET with the above does the following: 
  5055.  
  5056.    1. The data in *recordStruct is used as the new record that is to replace 
  5057.       the data record at AP.recNo.  The data file was linked to this index file 
  5058.       (AP.handle) during the index open, in OP.xbLink. 
  5059.  
  5060.    2. If the record data in *recordStruct is the same as the original disk 
  5061.       record, nothing is done.  If the data is new, the key fields are compared 
  5062.       to that belonging to the original disk record, and if the same, only the 
  5063.       record data is updated.  If the new record's key differs from the 
  5064.       original's, the original key for this record is removed from the index, 
  5065.       and the new key inserted. 
  5066.  
  5067.    3. The operation performed directly above is repeated, this time for the 
  5068.       second index file.  The new record data, and the record number to update 
  5069.       are, for this particular example, the same. 
  5070.  
  5071.  AP.recNo must be set to the record number that you are updating. Each 
  5072.  AP[].recNo must be set to a valid record number, even if the record number is 
  5073.  the same as the previous AP[] pack's (the case where you have more than one 
  5074.  index file for a data file).  BULLET knows if the record number duplicates a 
  5075.  number in a previous AP pack, and allocates resources for only the first 
  5076.  encounter of the data record.  Subsequent encounters refer to the first. 
  5077.  
  5078.  Upon return, if no error, the return code is 0.  If the new and original data 
  5079.  records differ, the key for the new data record, including any enumerator, is 
  5080.  in the buffer at AP[0].keyPtr.  This even if the key fields did not change. 
  5081.  The same applies to the second index, with the new data key in AP[1].keyPtr. 
  5082.  
  5083.  Upon return, and there was an error, the return code can be -2, -1, 1, or 2. 
  5084.  If negative, the error was caused during processing of that AP pack's data 
  5085.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5086.  is the return code, and -1 since C arrays start at 0).  If the return code was 
  5087.  positive, the error was caused during processing of that AP pack's index file, 
  5088.  and the error code itself is in AP[rez-1].stat, as well.  The return code is, 
  5089.  as in all BULLET transaction-list routines, an index of the AP pack that 
  5090.  generated the error -- negative if a data file error, positive if an index 
  5091.  file error. 
  5092.  
  5093.  Note:  If an error occurred after any part of the database had changed (during 
  5094.  this particular call), then any and all changes that were made are backed-out, 
  5095.  and the files restored to the same state as before the call. 
  5096.  
  5097.  Example: Specifying two index files for each of two different data files 
  5098.  
  5099.  Four total files: two index files related to one data file, and two other 
  5100.  index files related to another data file, would set AccessPack to: 
  5101.  
  5102.   AP[0].func = UPDATE_XB;
  5103.   AP[0].handle = indexHandle_0;
  5104.   AP[0].recNo = recordToUpdate_0;
  5105.   AP[0].recPtr = &recordStruct_0;
  5106.   AP[0].keyPtr = keyBuffer_0;
  5107.   AP[0].nextPtr = AP[1];
  5108.  
  5109.   AP[1].handle = indexHandle_1;
  5110.   AP[1].recNo = recordToUpdate_0;
  5111.   AP[1].recPtr = &recordStruct_0;
  5112.   AP[1].keyPtr = keyBuffer_1;
  5113.   AP[1].nextPtr = AP[2];
  5114.  
  5115.   AP[2].handle = indexHandle_2;
  5116.   AP[2].recNo = recordToUpdate_1;
  5117.   AP[2].recPtr = &recordStruct_1;
  5118.   AP[2].keyPtr = keyBuffer_2;
  5119.   AP[2].nextPtr = AP[3];
  5120.  
  5121.   AP[3].handle = indexHandle_3;
  5122.   AP[3].recNo = recordToUpdate_1;
  5123.   AP[3].recPtr = &recordStruct_1;
  5124.   AP[3].keyPtr = keyBuffer_3;
  5125.   AP[3].nextPtr = NULL;
  5126.  
  5127.  A call to BULLET with the above does the following: 
  5128.  
  5129.    1. The data in *recordStruct_0 is used as the new record that is to replace 
  5130.       the data record at AP[0].recNo in the data file linked to the index file 
  5131.       in AP[0].handle. 
  5132.  
  5133.    2. If the record data in *recordStruct_0 is the same as the original disk 
  5134.       record, nothing is done.  If the data is new, the key fields are compared 
  5135.       to that belonging to the original disk record, and if the same, only the 
  5136.       record data is updated.  If the new record's key differs from the 
  5137.       original's, the original key for this record is removed from the index, 
  5138.       and the new key inserted. 
  5139.  
  5140.    3. The operation performed directly above is repeated, this time for the 
  5141.       second index file.  The new record data, and the record number to update, 
  5142.       are for this particular example, the same. 
  5143.  
  5144.    4. The data in *recordStruct_1 is used as the new record that is to replace 
  5145.       the data record at AP[2].recNo in the data file linked to the index file 
  5146.       in AP[2].handle. 
  5147.  
  5148.    5. If the record data in *recordStruct_1 is the same as the original disk 
  5149.       record, nothing is done.  If the data is new, the key fields are compared 
  5150.       to that belonging to the original disk record, and if the same, only the 
  5151.       record data is updated.  If the new record's key differs from the 
  5152.       original's, the original key for this record is removed from the index, 
  5153.       and the new key inserted. 
  5154.  
  5155.    6. The operation performed directly above is repeated, this time for the 
  5156.       fourth index file.  The new record data, and the record number to update 
  5157.       are, for this particular example, the same. 
  5158.  
  5159.  Upon return, if no error, the return code is 0.  If the new and original data 
  5160.  records differ, the keys for the new data records, including any enumerators, 
  5161.  are in the buffers at AP[0].keyPtr to AP[3].keyPtr.  This even if the key 
  5162.  fields did not change.  If one, or all, of the new data records matched the 
  5163.  original data record, nothing is placed in *keyBuffer for that index. 
  5164.  
  5165.  Upon return, and there was an error, the return code can be -4 to -1, or 1 to 
  5166.  4.  If negative, the error was caused during processing of that AP pack's data 
  5167.  file portion, and the error code itself is in AP[abs(rez)-1].stat (where rez 
  5168.  is the return code, and rez-1 since C arrays start at 0).  If the return code 
  5169.  was positive, the error was caused during processing of that AP pack's index 
  5170.  file, and the error code itself is in AP[rez-1].stat, as well.  The return 
  5171.  code is, as in all BULLET transaction-list routines, an index of the AP pack 
  5172.  that generated the error -- negative if a data file error, positive if an 
  5173.  index file error. 
  5174.  
  5175.  Note:  If an error occurred after any part of the database had changed (during 
  5176.  this particular call), then any and all changes that were made are backed-out, 
  5177.  and the files restored to the same state as before the call. 
  5178.  
  5179.  Example: Specifying two index files for two records in the same data file 
  5180.  
  5181.  Three files: two index files related to one data file, where two data records 
  5182.  are to be updated, would set AccessPack to: 
  5183.  
  5184.   AP[0].func = UPDATE_XB;
  5185.   AP[0].handle = indexHandle_0;
  5186.   AP[0].recNo = recordToUpdate_0;
  5187.   AP[0].recPtr = &recordStruct_0;
  5188.   AP[0].keyPtr = keyBuffer_0;
  5189.   AP[0].nextPtr = AP[1];
  5190.  
  5191.   AP[1].handle = indexHandle_1;
  5192.   AP[1].recNo = recordToUpdate_0;
  5193.   AP[1].recPtr = &recordStruct_0;
  5194.   AP[1].keyPtr = keyBuffer_1;
  5195.   AP[1].nextPtr = AP[2];
  5196.  
  5197.   AP[2].handle = indexHandle_0;
  5198.   AP[2].recNo = recordToUpdate_1;
  5199.   AP[2].recPtr = &recordStruct_1;
  5200.   AP[2].keyPtr = keyBuffer_2;
  5201.   AP[2].nextPtr = AP[3];
  5202.  
  5203.   AP[3].handle = indexHandle_1;
  5204.   AP[3].recNo = recordToUpdate_1;
  5205.   AP[3].recPtr = &recordStruct_1;
  5206.   AP[3].keyPtr = keyBuffer_3;
  5207.   AP[3].nextPtr = NULL;
  5208.  
  5209.  A call to BULLET with the above does the following: 
  5210.  
  5211.    1. The data in *recordStruct_0 is used as the new record that is to replace 
  5212.       the data record at AP[0].recNo in the data file linked to the index file 
  5213.       in AP[0].handle. 
  5214.  
  5215.    2. If the record data in *recordStruct_0 is the same as the original disk 
  5216.       record, nothing is done.  If the data is new, the key fields are compared 
  5217.       to that belonging to the original disk record, and if the same, only the 
  5218.       record data is updated.  If the new record's key differs from the 
  5219.       original's, the original key for this record is removed from the index, 
  5220.       and the new key inserted. 
  5221.  
  5222.    3. The operation performed directly above is repeated, this time for the 
  5223.       second index file.  The new record data, and the record number to update, 
  5224.       are for this particular example, the same. 
  5225.  
  5226.    4. The data in *recordStruct_1 is used as the new record that is to replace 
  5227.       the data record at AP[2].recNo in the data file linked to the index file 
  5228.       in AP[2].handle.  This is the same index file as the first AP pack, and 
  5229.       also the same data file.  However, this is a different record number. 
  5230.  
  5231.    5. If the record data in *recordStruct_1 is the same as the original disk 
  5232.       record, nothing is done.  If the data is new, the key fields are compared 
  5233.       to that belonging to the original disk record, and if the same, only the 
  5234.       record data is updated.  If the new record's key differs from the 
  5235.       original's, the original key for this record is removed from the index, 
  5236.       and the new key inserted. 
  5237.  
  5238.    6. The operation performed directly above is repeated, this time for the 
  5239.       fourth index file. The new record data, and the record number to update 
  5240.       are, for this particular example, the same. 
  5241.  The return ritual is as described above, for "Specifying two index files each 
  5242.  for two different data files". 
  5243.  
  5244.  
  5245. ΓòÉΓòÉΓòÉ 9.58. REINDEX_XB ΓòÉΓòÉΓòÉ
  5246.  
  5247. Pack: ACCESSPACK               Source Example 
  5248.  
  5249.      IN               OUT
  5250.    AP.func          AP.stat
  5251.    AP.handle        AP.recNo
  5252.    AP.keyPtr        *AP.keyPtr
  5253.    AP.nextPtr
  5254.  
  5255.  Reindex all files in the transaction list, re-evaluating the key expression in 
  5256.  the process. 
  5257.  
  5258.  This routine is used to reindex up to 256 index files per call. The index 
  5259.  files must already exist and be open.  Any existing key values are overwritten 
  5260.  by new key data.  In other words, if you have a 100MB index file, REINDEX_XB 
  5261.  uses the same file space, building new keys over old.  This results in a less 
  5262.  fragmented disk and also minimizes disk space needed.  You can also create a 
  5263.  new, empty index file and reindex to that.  This would be useful, for 
  5264.  instance, if you needed to create a temporary index file -- something that 
  5265.  you'd use for a report, say, then delete after the report.  Another use for 
  5266.  creating a new index file and reindexing to that is to, after creating it 
  5267.  (COPY_INDEX_HEADER_XB can be used), use EXPAND_FILE_DOS and expand it to the 
  5268.  expected size.  This has the benefit of ensuring that this file allocation is 
  5269.  as contiguous as the file system allows (without relying on OS/API-specific 
  5270.  calls). 
  5271.  
  5272.  If the routine failed to complete, the function return value is the number 
  5273.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5274.  the failure was from an index operation; a negative number indicates the 
  5275.  failure was from a data operation (reading the data file).  In each case, the 
  5276.  absolute value of the return code is the list item that failed (the pack 
  5277.  index).  For example, if five index handles are in the list(AP[0] to AP[4]), 
  5278.  and an error occurred on the last pack's index file, the return code would be 
  5279.  positive 5, indicating the fifth pack (AP[4]) failed.  Since it was a positive 
  5280.  5, the index file was being processed when the error occurred.  Being 
  5281.  processed means not only physical access, but verification, etc.  If the 
  5282.  return code was -5, then again, the error was in the fifth pack, but since it 
  5283.  is negative, the error occurred while processing the data file. 
  5284.  
  5285.  Unlike INSERT_XB and UPDATE_XB, each pack need not include a separate key 
  5286.  buffer; you may share a common key buffer.  If duplicate keys are generated in 
  5287.  the reindex process and the sort function does not flag DUPS_ALLOWED, an error 
  5288.  is returned.  The duplicate key is in *AP.keyPtr and the record number it was 
  5289.  generated from in AP.recNo.  Since no roll-back is performed, there is only a 
  5290.  real need for a single key buffer.  You may use separate ones, too. 
  5291.  
  5292.  This routine creates a temporary work file in either the current directory or, 
  5293.  if the environment variable TMP is defined, in the directory pointed to by 
  5294.  TMP=.  The path used for this temporary file may also be specified at run-time 
  5295.  by using the TMP_PATH_PTR item for SET_SYSVARS_XB.  If TMP_PATH_PTR is NULL 
  5296.  (default), then TMP= is used, or if that is not found, then the current 
  5297.  directory is used.  The size of this temporary file is, in bytes, 
  5298.  approximately (keylength+4) * number of records in the data file.  The 
  5299.  resultant index files are, by default, optimized for minimum size and maximum 
  5300.  retrieval speed.  This full-node packing leaves one empty key per node, which 
  5301.  means b-tree splitting will occur almost immediately upon inserting data (with 
  5302.  INSERT_XB or STORE_KEY_XB). 
  5303.  
  5304.  This behaviour can be modified with the REINDEX_PACK_PCT item for 
  5305.  SET_SYSVARS_XB so that less packing is done.  Less packing would improve 
  5306.  subsequent INSERT_XB performance since all nodes are not almost full as they 
  5307.  are with a full pack.  File size and retrieval times increase, though, but 
  5308.  perhaps not noticeably. 
  5309.  
  5310.  During the reindex process, each record is checked for a matching skip-tag 
  5311.  value, as set in SET_SYSVARS_XB.  The skip-tag is set to 0 by default, where 
  5312.  no check is done and keys for all records in the data file are inserted into 
  5313.  the index file. 
  5314.  
  5315.  
  5316. ΓòÉΓòÉΓòÉ 9.59. LOCK_XB ΓòÉΓòÉΓòÉ
  5317.  
  5318. Pack: LOCKPACK                 Source Example 
  5319.  
  5320.      IN               OUT
  5321.    LP.func          LP.stat
  5322.    LP.handle
  5323.    LP.xlMode
  5324.    LP.dlMode
  5325.    LP.recStart=0
  5326.    LP.nextPtr
  5327.  
  5328.  Lock all bytes of the files in the list for exclusive use by the current 
  5329.  process, and reload file headers from disk.  LP.recStart must be 0 for each 
  5330.  pack. 
  5331.  
  5332.  This routine is used to lock the database for either exclusive use by this 
  5333.  process, or shared access (allowing any process to read, but not write, to the 
  5334.  files).  Up to 256 index files may be locked per call, as well as 256 data 
  5335.  files, too, for a total of 512 files per single LOCK_XB call.  Shared-access 
  5336.  locking prevents all processes from writing to the file while a shared lock is 
  5337.  in force, including this process.  To relock in exclusive lock mode, without 
  5338.  unlocking first, use: RELOCK_XB. 
  5339.  
  5340.  Only index handles are listed in AP.handle.  Each index file has associated 
  5341.  with it a data file, known internally to BULLET (the xbLink from OPEN_XB). 
  5342.  There may be more than one index file for a data file, but there is always one 
  5343.  data file per index handle specified in the list.  For example, you can list 
  5344.  five index files, each indexing the same xbLink data file, and have BULLET 
  5345.  perform an atomic lock of that list. 
  5346.  
  5347.  LP.xlMode is set to 1 to perform a shared lock on the index file.  Set to 0 
  5348.  for an exclusive lock.  A shared lock allows only reading. 
  5349.  
  5350.  LP.dlMode is set to 1 to perform a shared lock on the data file.  Set to 0 for 
  5351.  an exclusive lock.  A shared lock allows only reading. 
  5352.  
  5353.  The lock mode (shared <-> exclusive) can be changed using RELOCK_XB. 
  5354.  
  5355.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5356.  upon the first lock request (or on a relock request).  It is only on this 
  5357.  first lock request that the header is reloaded.  When the lock count returns 
  5358.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5359.  required.  Only full-locks are maintained in this way.  The number of 
  5360.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5361.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5362.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5363.  you can lock a file 100 times in a row, but only on the first lock are any 
  5364.  operations actually performed, and only on the last unlock are any performed. 
  5365.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5366.  increment or decrement the lock count for that handle. 
  5367.  
  5368.  This, and several other routines, are transaction-list-based.  This means that 
  5369.  if a failure occurs prior to the routine's completion, all locks made to the 
  5370.  database by this routine will be unlocked. 
  5371.  
  5372.  If the routine failed to complete, the function return value is the number 
  5373.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5374.  the failure was from an index operation; a negative number indicates the 
  5375.  failure was from a data operation.  In each case, the absolute value of the 
  5376.  return code is the list item that failed (the pack index).  For example, if 
  5377.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  5378.  the last pack's index file, the return code would be positive 5, indicating 
  5379.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  5380.  being processed when the error occurred.  Being processed means not only 
  5381.  physical access, but verification, etc.  If the return code was -5, then 
  5382.  again, the error was in the fifth pack, but since it is negative, the error 
  5383.  occurred while processing the data file.  In either case, upon return, any 
  5384.  files locked during this call are unlocked before returning. 
  5385.  
  5386.  The advantage of using region locks (LOCK_XB locks entire file regions) to 
  5387.  control file access is that the file does not need to be opened/closed using 
  5388.  the Deny Read/Write sharing attribute.  Opening the file for Deny None, and 
  5389.  controlling subsequent access with region locks, allows for faster processing 
  5390.  since files do not need to be constantly opened and closed, as they would if 
  5391.  access were controlled by opening with Deny Read/Write. 
  5392.  
  5393.  Using the operating system to control access also prevents other processes 
  5394.  from accessing the files.  Other methods, such as internal locking (such as 
  5395.  using 'L' in the tag field as a program-aware in-use flag), work fine so long 
  5396.  as each process accessing the files knows about this internal "locking". 
  5397.  However, since it's proprietary, other processes may not know about it.  Any 
  5398.  locking system that is not commonly shared throughout the system is not 
  5399.  effective when it comes to preventing other processes from corrupting files. 
  5400.  
  5401.  Note:  Region locking prevents other processes from both writing and reading 
  5402.  the locked file.  For operating systems that do not provide shared locks, and 
  5403.  read-access is required at all times, you may specify this type access with 
  5404.  the access-sharing mode when the BULLET file is opened.  Once opened for this 
  5405.  (R/W, DenyWrite) then only the current process can write to the file until it 
  5406.  is closed.  Other processes must open the file for Read-Only access.  For 
  5407.  small networks (two or three nodes), this may be suitable.  Otherwise, region 
  5408.  locking is much preferred, and very much faster, since files do not have to be 
  5409.  opened and closed every time the access state needs to change. 
  5410.  
  5411.  
  5412. ΓòÉΓòÉΓòÉ 9.60. UNLOCK_XB ΓòÉΓòÉΓòÉ
  5413.  
  5414. Pack: LOCKPACK                 Source Example 
  5415.  
  5416.      IN               OUT
  5417.    LP.func          LP.stat
  5418.    LP.handle
  5419.    LP.recStart=0
  5420.    LP.nextPtr
  5421.  
  5422.  Unlock all bytes in the specified files (previously locked) and flush the 
  5423.  files' headers to disk (the flush is done before the locks are released). Also 
  5424.  unlock all bytes in the related data file and flush the data file header to 
  5425.  disk.  LP.recStart must be 0 for each pack. 
  5426.  
  5427.  Note:  If a shared-lock is active for this handle (as set by this process), 
  5428.  the flush is not performed.  This because writing to the locked region is not 
  5429.  permitted (nor is the flush required since nothing could have been changed). 
  5430.  
  5431.  If the routine failed to complete, the function return value is the number 
  5432.  (1-based) of the pack that caused the failure.  A positive number indicates 
  5433.  the failure was from an index operation; a negative number indicates the 
  5434.  failure was from a data operation.  In each case, the absolute value of the 
  5435.  return code is the list item that failed (the pack index).  For example, if 
  5436.  five index handles are in the list(AP[0] to AP[4]), and an error occurred on 
  5437.  the last pack's index file, the return code would be positive 5, indicating 
  5438.  the fifth pack (AP[4]) failed.  Since it was a positive 5, the index file was 
  5439.  being processed when the error occurred.  Being processed means not only 
  5440.  physical access, but verification, etc.  If the return code was -5, then 
  5441.  again, the error was in the fifth pack, but since it is negative, the error 
  5442.  occurred while processing the data file. 
  5443.  
  5444.  This routine does not attempt to re-lock those files unlocked successfully if 
  5445.  an error occurs in the transaction.  If an error does occur (unlikely), the 
  5446.  remaining files must be manually unlocked with the UNLOCK_KEY_XB and 
  5447.  UNLOCK_DATA_XB routines. 
  5448.  
  5449.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5450.  upon the first lock request (or on a relock request).  It is only on this 
  5451.  first lock request that the header is reloaded.  When the lock count returns 
  5452.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5453.  required.  Only full-locks are maintained in this way.  The number of 
  5454.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5455.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5456.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5457.  you can lock a file 100 times in a row, but only on the first lock are any 
  5458.  operations actually performed, and only on the last unlock are any performed. 
  5459.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5460.  increment or decrement the lock count for that handle. 
  5461.  
  5462.  
  5463. ΓòÉΓòÉΓòÉ 9.61. LOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  5464.  
  5465. Pack: LOCKPACK                 Source Example 
  5466.  
  5467.      IN               OUT
  5468.    LP.func          LP.stat
  5469.    LP.handle
  5470.    LP.xlMode
  5471.  
  5472.  Lock all bytes of the index file for exclusive use by the current process and 
  5473.  reload the index file's header from disk. 
  5474.  
  5475.  LP.xlMode is set to 1 to perform a shared lock.  Set to 0 for an exclusive 
  5476.  lock.  A shared lock allows only reading.  The lock mode (shared <-> 
  5477.  exclusive) can be changed using RELOCK_INDEX_XB. 
  5478.  
  5479.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5480.  upon the first lock request (or on a relock request).  It is only on this 
  5481.  first lock request that the header is reloaded.  When the lock count returns 
  5482.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5483.  required.  Only full-locks are maintained in this way.  The number of 
  5484.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5485.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5486.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5487.  you can lock a file 100 times in a row, but only on the first lock are any 
  5488.  operations actually performed, and only on the last unlock are any performed. 
  5489.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5490.  increment or decrement the lock count for that handle. 
  5491.  
  5492.  
  5493. ΓòÉΓòÉΓòÉ 9.62. UNLOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  5494.  
  5495. Pack: LOCKPACK                 Source Example 
  5496.  
  5497.      IN               OUT
  5498.    LP.func          LP.stat
  5499.    LP.handle
  5500.  
  5501.  Unlock all bytes in the specified file (previously locked) and flush the 
  5502.  file's header to disk (the flush is done before the locks are released). 
  5503.  
  5504.  If the current lock state is shared, the flush is not performed. 
  5505.  
  5506.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5507.  upon the first lock request (or on a relock request).  It is only on this 
  5508.  first lock request that the header is reloaded.  When the lock count returns 
  5509.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5510.  required.  Only full-locks are maintained in this way.  The number of 
  5511.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5512.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5513.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5514.  you can lock a file 100 times in a row, but only on the first lock are any 
  5515.  operations actually performed, and only on the last unlock are any performed. 
  5516.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5517.  increment or decrement the lock count for that handle. 
  5518.  
  5519.  
  5520. ΓòÉΓòÉΓòÉ 9.63. LOCK_DATA_XB ΓòÉΓòÉΓòÉ
  5521.  
  5522. Pack: LOCKPACK                 Source Example 
  5523.  
  5524.      IN               OUT
  5525.    LP.func          LP.stat
  5526.    LP.handle
  5527.    LP.dlMode
  5528.    LP.recStart
  5529.    LP.recCount
  5530.  
  5531.  Lock all bytes of the data file specified in LP.handle for exclusive use by 
  5532.  the current process.  It also reloads the data file header from disk. You must 
  5533.  set LP.recStart=0 to lock all bytes.  To lock a single record, or a set of 
  5534.  contiguous records, set LP.recStart to the first record to lock and 
  5535.  LP.recCount to the number of records to lock. 
  5536.  
  5537.  Header re-loading is performed only if locking all bytes. 
  5538.  
  5539.  If LP.recStart is not 0, be aware that the header is not locked, nor is it 
  5540.  re-loaded.  Also, maintaining a lock on the single record prevents any other 
  5541.  process from doing a full lock on that data file, thereby preventing write 
  5542.  access to the file from any other BULLET process using LOCK_XB, but not 
  5543.  necessarily preventing other applications from writing to that file.  That may 
  5544.  or may not be good.  It does not prevent other BULLET processes from reading 
  5545.  that file (except for that locked record). 
  5546.  
  5547.  Multiple single records are allowed, but each must then be unlocked 
  5548.  individually, in the same format (start, count) as the lock. 
  5549.  
  5550.  LP.dlMode is set to 1 to perform a shared lock.  Set to 0 for an exclusive 
  5551.  lock.  A shared lock allows only reading.  The lock mode (shared <-> 
  5552.  exclusive) can be changed using RELOCK_DATA_XB. 
  5553.  
  5554.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5555.  upon the first lock request (or on a relock request).  It is only on this 
  5556.  first lock request that the header is reloaded.  When the lock count returns 
  5557.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5558.  required.  Only full-locks are maintained in this way.  The number of 
  5559.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5560.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5561.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5562.  you can lock a file 100 times in a row, but only on the first lock are any 
  5563.  operations actually performed, and only on the last unlock are any performed. 
  5564.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5565.  increment or decrement the lock count for that handle. 
  5566.  
  5567.  
  5568. ΓòÉΓòÉΓòÉ 9.64. UNLOCK_DATA_XB ΓòÉΓòÉΓòÉ
  5569.  
  5570. Pack: LOCKPACK                 Source Example 
  5571.  
  5572.      IN               OUT
  5573.    LP.func          LP.stat
  5574.    LP.handle
  5575.    LP.recStart
  5576.    LP.recCount
  5577.  
  5578.  Unlock all bytes in the specified file handle (previously locked) and flush 
  5579.  the data file header to disk (the flush is done before the lock is released). 
  5580.  You must set LP.recStart=0 to unlock all bytes.  To unlock a single record, or 
  5581.  a set of contiguous records, set LP.recStart to the first record to unlock and 
  5582.  LP.recCount to the number of records to unlock. 
  5583.  
  5584.  Header flushing is performed only if unlocking a full lock. 
  5585.  
  5586.  An unlock must exactly mimic its corresponding lock.  This means if you lock 
  5587.  several records singly, you must unlock each of those records -- you cannot 
  5588.  use LP.recStart=0 to unlock singly-locked records. 
  5589.  
  5590.  Bullet maintains a per-handle lock count, and does a physical region lock only 
  5591.  upon the first lock request (or on a relock request).  It is only on this 
  5592.  first lock request that the header is reloaded.  When the lock count returns 
  5593.  to 0 (from UNLOCK_XB calls), it is at that time the header is flushed, if 
  5594.  required.  Only full-locks are maintained in this way.  The number of 
  5595.  outstanding locks can be determined from the SIP and SDP structures, from the 
  5596.  STAT_XB routines.  Note that individual LOCK_INDEX_XB and UNLOCK_INDEX_XB 
  5597.  routines, as well as the data ones, also act upon this lock count.  Therefore, 
  5598.  you can lock a file 100 times in a row, but only on the first lock are any 
  5599.  operations actually performed, and only on the last unlock are any performed. 
  5600.  Other lock/unlock calls (other than the first lock or last unlock) simply 
  5601.  increment or decrement the lock count for that handle. 
  5602.  
  5603.  
  5604. ΓòÉΓòÉΓòÉ 9.65. CHECK_REMOTE_XB ΓòÉΓòÉΓòÉ
  5605.  
  5606. Pack: REMOTEPACK               Source Example 
  5607.  
  5608.      IN               OUT
  5609.    RP.func          RP.stat
  5610.    RP.handle        RP.isRemote
  5611.       -or-          RP.flags=0
  5612.    RP.drive         RP.isShare=1
  5613.  
  5614.  If RP.handle is non-zero, determine if the specified handle of a file or 
  5615.  device is remote.  If the handle is local (e.g., not a network file or 
  5616.  device), RP.isRemote returns 0, otherwise it is remote.  RP.flags=0 and 
  5617.  RP.isShare=1 on return for either a handle or drive check under OS/2. 
  5618.  
  5619.  If RP.handle is zero, determine if the drive specified in RP.drive is remote. 
  5620.  Drive A: is 1, B: is 2, C: is 3, and so on.  To check the default drive use 0 
  5621.  (the default drive is the current drive).  If the drive is local (e.g., not a 
  5622.  network drive), RP.isRemote returns 0, otherwise it is remote. 
  5623.  
  5624.  The significance of the remote-ness is less important in a multitasking 
  5625.  environment since sharing of resources (files, in particular) must always be 
  5626.  managed, compared to single-tasking environments where, typically, sharing 
  5627.  (locking mechanisms) need only be performed when the resource is able to be 
  5628.  accessed by another process (ie is a 'network' drive).  Note that the resource 
  5629.  need not be located elsewhere to be classified as remote: Drives or devices or 
  5630.  files on the same machine may be classified as remote if the network software 
  5631.  is redirecting local access (such as on a server). 
  5632.  
  5633.  Note:  This routine is not mutex-protected. 
  5634.  
  5635.  
  5636. ΓòÉΓòÉΓòÉ 9.66. RELOCK_XB ΓòÉΓòÉΓòÉ
  5637.  
  5638. Pack: LOCKPACK                 Source Example 
  5639.  
  5640.      IN               OUT
  5641.    LP.func          LP.stat
  5642.    LP.handle
  5643.    LP.xlMode
  5644.    LP.dlMode
  5645.    LP.recStart=0
  5646.    LP.nextPtr
  5647.  
  5648.  Relock all bytes of the index files for the mode specified in LP.xlMode (index 
  5649.  files) and LP.dlMode (data files).  Also relock all bytes in the related data 
  5650.  file.  LP.recStart must be 0 for each pack. 
  5651.  
  5652.  Set LP.xlMode=1 to select a shared lock for the index file; set to 0 for an 
  5653.  exclusive lock.  Set LP.dlMode=1 to select a shared lock for the data file; 
  5654.  set to 0 for an exclusive lock. 
  5655.  
  5656.  If the lock mode is from exclusive to shared, the file is flushed before the 
  5657.  shared state is set.  BULLET maintains the current lock state and knows which 
  5658.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  5659.  determined by the SIP and SDP structures from the STAT_XB routines.  This 
  5660.  routine does not affect the lock count, nor are the headers reloaded (nor 
  5661.  should they be). 
  5662.  
  5663.  The lock state is on a file handle basis, not on an LP[] pack basis. This 
  5664.  means the file, as identified by the handle, is in the lock state last set. 
  5665.  
  5666.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  5667.  locking again in the new state, this performs all operations without the 
  5668.  possibility that another process can grab the lock away. 
  5669.  
  5670.  
  5671. ΓòÉΓòÉΓòÉ 9.67. RELOCK_INDEX_XB ΓòÉΓòÉΓòÉ
  5672.  
  5673. Pack: LOCKPACK                 Source Example 
  5674.  
  5675.      IN               OUT
  5676.    LP.func          LP.stat
  5677.    LP.handle
  5678.    LP.xlMode
  5679.  
  5680.  Relock all bytes of the index file for the mode specified in LP.xlMode and 
  5681.  reload the header. 
  5682.  
  5683.  Set LP.xlMode=1 to select a shared lock; set to 0 for an exclusive lock. If 
  5684.  the lock mode is from exclusive to shared, the file is flushed before the 
  5685.  shared state is set.  BULLET maintains the current lock state and knows which 
  5686.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  5687.  determined by the SIP structure from the STAT_INDEX_XB routine.  This routine 
  5688.  does not affect the lock count, nor is the header reloaded (nor should it be). 
  5689.  
  5690.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  5691.  locking again in the new state, this performs all operations without the 
  5692.  possibility that another process can grab the lock away. 
  5693.  
  5694.  
  5695. ΓòÉΓòÉΓòÉ 9.68. RELOCK_DATA_XB ΓòÉΓòÉΓòÉ
  5696.  
  5697. Pack: LOCKPACK                 Source Example 
  5698.  
  5699.      IN               OUT
  5700.    LP.func          LP.stat
  5701.    LP.handle
  5702.    LP.dlMode
  5703.    LP.recStart
  5704.    LP.recCount
  5705.  
  5706.  Relock all bytes of the data file for the mode specified in LP.dlMode and 
  5707.  reload the header, unless LP.recStart is non-zero. 
  5708.  
  5709.  If the lock mode is from exclusive to shared, the file is flushed before the 
  5710.  shared state is set.  BULLET maintains the current lock state and knows which 
  5711.  direction the lock is going in.  The lock state (shared or exclusive) can be 
  5712.  determined by the SDP structure from the STAT_DATA_XB routine.  This routine 
  5713.  does not affect the lock count, nor is the header reloaded (nor should it be). 
  5714.  
  5715.  You must set LP.recStart=0 to relock all bytes.  To relock a single record, or 
  5716.  set of contiguous records, set LP.recStart=record# to relock and LP.recCount 
  5717.  to the number of records to relock. 
  5718.  
  5719.  Note:  The lock switch is made atomic:  Rather than unlocking, and then 
  5720.  locking again in the new state, this performs all operations without the 
  5721.  possibility that another process can grab the lock away. 
  5722.  
  5723.  
  5724. ΓòÉΓòÉΓòÉ 9.69. DELETE_FILE_DOS ΓòÉΓòÉΓòÉ
  5725.  
  5726. Pack: DOSFILEPACK              Source Example 
  5727.  
  5728.      IN               OUT
  5729.    DFP.func         DFP.stat
  5730.    DFP.filenamePtr
  5731.  
  5732.  Delete the specified file. 
  5733.  
  5734.  Note:  OS/2 DosForceDelete is used so the file is not recoverable with the 
  5735.  UNDELETE command. 
  5736.  
  5737.  
  5738. ΓòÉΓòÉΓòÉ 9.70. RENAME_FILE_DOS ΓòÉΓòÉΓòÉ
  5739.  
  5740. Pack: DOSFILEPACK              Source Example 
  5741.  
  5742.      IN               OUT
  5743.    DFP.func         DFP.stat
  5744.    DFP.filenamePtr
  5745.    DFP.newNamePtr
  5746.  
  5747.  Rename a file.  May also be used to move the file to a new directory within 
  5748.  the partition. 
  5749.  
  5750.  If the specified directory differs from the file's directory, the file's 
  5751.  directory entry is moved to the new directory. 
  5752.  
  5753.  For example, if the filenamePtr filename is /LP100/PROJ94A.INF and the 
  5754.  newFilenamePtr filename is /ARCH/PROJ93A.INA, the file is essentially renamed 
  5755.  and also moved to the /ARCH directory. 
  5756.  
  5757.  
  5758. ΓòÉΓòÉΓòÉ 9.71. CREATE_FILE_DOS ΓòÉΓòÉΓòÉ
  5759.  
  5760. Pack: DOSFILEPACK              Source Example 
  5761.  
  5762.      IN               OUT
  5763.    DFP.func         DFP.stat
  5764.    DFP.filenamePtr
  5765.    DFP.attr
  5766.  
  5767.  Create a new file. 
  5768.  
  5769.  The specified filename/pathname must not already exist. 
  5770.  
  5771.  The file created is not left open.  You must OPEN_FILE_DOS to use it. 
  5772.  
  5773.  The attribute used during the create can be: 
  5774.  
  5775.    Attribute  Value   Meaning
  5776.     Normal       0      normal access permitted to file
  5777.     Read-Only    1      read-only access permitted to file
  5778.     Hidden       2      file does not appear in directory listing
  5779.     System       4      file is a system file
  5780.     SubDir      10h     FILENAME is a subdirectory
  5781.     Archive     20h     file is marked for archiving
  5782.  
  5783.  Note:  Use MAKE_DIR_DOS to create a subdirectory. 
  5784.  
  5785.  
  5786. ΓòÉΓòÉΓòÉ 9.72. ACCESS_FILE_DOS ΓòÉΓòÉΓòÉ
  5787.  
  5788. Pack: DOSFILEPACK              Source Example 
  5789.  
  5790.      IN               OUT
  5791.    DFP.func         DFP.stat
  5792.    DFP.filenamePtr
  5793.    DFP.asMode
  5794.  
  5795.  Determine if the specified file can be accessed with the specified 
  5796.  access-sharing mode. 
  5797.  
  5798.  Basically, a Does-File-Exist routine.  It uses the specified access-sharing 
  5799.  mode when trying to open the file.  For example, if you specify DFP.attr = 
  5800.  0x0042 (R/W access + Deny None sharing) and issue ACCESS_FILE_DOS on a 
  5801.  Read-Only file, an error is returned.  A sharing mode must be specified; it 
  5802.  cannot be left 0. 
  5803.  
  5804.  
  5805. ΓòÉΓòÉΓòÉ 9.73. OPEN_FILE_DOS ΓòÉΓòÉΓòÉ
  5806.  
  5807. Pack: DOSFILEPACK              Source Example 
  5808.  
  5809.      IN               OUT
  5810.    DFP.func         DFP.stat
  5811.    DFP.filenamePtr  DFP.handle
  5812.    DFP.asMode
  5813.  
  5814.  Open the file with the access-sharing mode, returning the handle on success. 
  5815.  
  5816.  
  5817. ΓòÉΓòÉΓòÉ 9.74. SEEK_FILE_DOS ΓòÉΓòÉΓòÉ
  5818.  
  5819. Pack: DOSFILEPACK              Source Example 
  5820.  
  5821.      IN               OUT
  5822.    DFP.func         DFP.stat
  5823.    DFP.handle       DFP.seekTo
  5824.    DFP.seekTo
  5825.    DFP.method
  5826.  
  5827.  Position the file pointer of the file to the seekTo position based on the 
  5828.  method specified. 
  5829.  
  5830.  The position is a 32-bit value and is relative to either the start of the 
  5831.  file, the current file pointer position, or the end of the file. 
  5832.  
  5833.   Method   Meaning
  5834.     0      start move from the start of file (offset is a 32-bit unsigned value)
  5835.     1      start move at the current position (offset a signed value)
  5836.     2      start move at the end of file (offset a signed value)
  5837.  For example, to move to the last byte of a sector (512th byte, but offset 
  5838.  511), set the offset value to 511 and use Method 0.  On return, the absolute 
  5839.  offset value of the new position is returned.  This return value is useful 
  5840.  with Method 2 since you can specify an offset of 0 and have the file length 
  5841.  returned.  To move to the start of the file, use method 0, offset 0.  To move 
  5842.  to the first byte of the second sector, use offset 512. 
  5843.  
  5844.  Note:  Never position the file pointer to before the start of file. 
  5845.  
  5846.  
  5847. ΓòÉΓòÉΓòÉ 9.75. READ_FILE_DOS ΓòÉΓòÉΓòÉ
  5848.  
  5849. Pack: DOSFILEPACK              Source Example 
  5850.  
  5851.      IN               OUT
  5852.    DFP.func         DFP.stat
  5853.    DFP.handle       DFP.bytes
  5854.    DFP.bytes
  5855.    DFP.bufferPtr
  5856.  
  5857.  Read from the file or device the specified number of bytes into a buffer. 
  5858.  
  5859.  On block devices (such as disks) input starts at the current file position and 
  5860.  the file pointer is repositioned to the last byte read +1. 
  5861.  
  5862.  It is possible to read less than the bytes specified without an error being 
  5863.  generated.  Compare the bytes to read with the returned bytes read value.  If 
  5864.  less then end of file was reached during the read.  If 0 then file was already 
  5865.  at EOF. 
  5866.  
  5867.  
  5868. ΓòÉΓòÉΓòÉ 9.76. EXPAND_FILE_DOS ΓòÉΓòÉΓòÉ
  5869.  
  5870. Pack: DOSFILEPACK              Source Example 
  5871.  
  5872.      IN               OUT
  5873.    DFP.func         DFP.stat
  5874.    DFP.handle
  5875.    DFP.bytes
  5876.  
  5877.  Expands the file by the number of bytes beyond its current size. 
  5878.  
  5879.  This routine is useful in pre-allocating disk space.  By reserving disk space 
  5880.  in advance you can guarantee that enough disk space will be available for a 
  5881.  future operation (especially if more than 1 process is running). You'll also 
  5882.  be able ensure that the disk space that a file does use is as contiguous as 
  5883.  possible. 
  5884.  
  5885.  Database systems are dynamic and their files typically allocate new space on 
  5886.  an as-needed basis.  This dynamic allocation can cause parts of a file to be 
  5887.  located throughout the disk system, possibly affecting performance 
  5888.  drastically.  By pre-allocating the disk space you can be assured of 
  5889.  consistent throughput performance since the file is contiguous. 
  5890.  
  5891.  
  5892. ΓòÉΓòÉΓòÉ 9.77. WRITE_FILE_DOS ΓòÉΓòÉΓòÉ
  5893.  
  5894. Pack: DOSFILEPACK              Source Example 
  5895.  
  5896.      IN               OUT
  5897.    DFP.func         DFP.stat
  5898.    DFP.handle       DFP.bytes
  5899.    DFP.bytes
  5900.    DFP.bufferPtr
  5901.  
  5902.  Write to the file or device the specified number of bytes from a buffer. 
  5903.  
  5904.  If the number of bytes written is less than the specified bytes, this routine 
  5905.  returns an error. 
  5906.  
  5907.  On block devices (such as disk) output starts at the current file position, 
  5908.  and the file pointer is repositioned to the last byte written +1. 
  5909.  
  5910.  Note:  If the specified bytes to write is 0, the file is truncated at the 
  5911.  current file pointer position. 
  5912.  
  5913.  
  5914. ΓòÉΓòÉΓòÉ 9.78. CLOSE_FILE_DOS ΓòÉΓòÉΓòÉ
  5915.  
  5916. Pack: DOSFILEPACK              Source Example 
  5917.  
  5918.      IN               OUT
  5919.    DFP.func         DFP.stat
  5920.    DFP.handle
  5921.  
  5922.  Close the file flushing any internal buffers, releasing any locked regions, 
  5923.  and updating the directory entry to the correct size, date, and time. 
  5924.  
  5925.  
  5926. ΓòÉΓòÉΓòÉ 9.79. MAKE_DIR_DOS ΓòÉΓòÉΓòÉ
  5927.  
  5928. Pack: DOSFILEPACK              Source Example 
  5929.  
  5930.      IN               OUT
  5931.    DFP.func         DFP.stat
  5932.    DFP.filenamePtr
  5933.  
  5934.  Create a new subdirectory. 
  5935.  
  5936.  
  5937. ΓòÉΓòÉΓòÉ 9.80. COMMIT_FILE_DOS ΓòÉΓòÉΓòÉ
  5938.  
  5939. Pack: DOSFILEPACK              Source Example 
  5940.  
  5941.      IN               OUT
  5942.    DFP.func         DFP.stat
  5943.    DFP.handle
  5944.  
  5945.  Flushes the OS system buffers for the handle, and updates the directory entry 
  5946.  for size. 
  5947.  
  5948.  
  5949. ΓòÉΓòÉΓòÉ 10. Bullet Source Examples ΓòÉΓòÉΓòÉ
  5950.  
  5951. Bullet source example excerpts for the C language follow.  Complete program 
  5952. source examples are provide on the included disk. 
  5953.  
  5954. In the examples, consider that 
  5955.  
  5956.         CHAR keyBuffer[64];
  5957.         AP.keyPtr = keyBuffer;
  5958.  
  5959. provides the compiler with a pointer whenever 'keyBuffer' is referenced, hence 
  5960. no need to use &keyBuffer.  Contrast this with a structure definition 
  5961.  
  5962.         struct yourRecordLayout yourRecord;
  5963.         AP.recPtr = &yourRecord;
  5964.  
  5965. where &yourRecord is required. 
  5966.  
  5967. Be aware of how you use zero-terminated strings, especially for fields that are 
  5968. not to be 0T'ed (DATE and NUMERIC fields, for example).  Use sscanf() and 
  5969. sprintf(), as required. 
  5970.  
  5971.  
  5972. ΓòÉΓòÉΓòÉ 10.1. Bullet Initialization ΓòÉΓòÉΓòÉ
  5973.  
  5974. /* All example source uses minimal error checking/handling throughout */
  5975. // comment marks are used throughout
  5976.  
  5977. // To simplify the source examples, error handling is typically of the form:
  5978. //
  5979. //   if (rez) goto ErrorHandler;
  5980. //
  5981. // Use suitable coding as you would normally handle the error.
  5982.  
  5983. #include "bullet2.h"
  5984.  
  5985. INITPACK IP;                    // packs used here
  5986.  
  5987. // INIT_XB must be the first Bullet routine used
  5988.  
  5989. IP.func = INIT_XB;              // start up Bullet
  5990. IP.JFTsize = 30;                // allow at least 30 files to be opened
  5991. rez = BULLET(&IP);
  5992. if (rez) return(rez);
  5993.  
  5994.  
  5995. ΓòÉΓòÉΓòÉ 10.2. Bullet Shutdown ΓòÉΓòÉΓòÉ
  5996.  
  5997. #include "bullet2.h"
  5998.  
  5999. EXITPACK EP;                    // packs used here
  6000.  
  6001. EP.func = EXIT_XB;              // shutdown Bullet
  6002. rez = BULLET(&EP);
  6003. if (rez) return(rez);
  6004.  
  6005.  
  6006. ΓòÉΓòÉΓòÉ 10.3. Memory Available ΓòÉΓòÉΓòÉ
  6007.  
  6008. #include "bullet2.h"
  6009.  
  6010. MEMORYPACK EP;                  // packs used here
  6011.  
  6012. MP.func = MEMORY_XB;
  6013. rez = BULLET(&MP);
  6014. if (rez==0) {
  6015.    printf("Memory result is not useful right now, but since you asked,\n");
  6016.    printf("the largest unused block of memory is right now at %d bytes\n",MP.memory);
  6017. }
  6018.  
  6019.  
  6020. ΓòÉΓòÉΓòÉ 10.4. File Backup Procedure ΓòÉΓòÉΓòÉ
  6021.  
  6022. #include "bullet2.h"
  6023.  
  6024. // code determines file type of handle, and selects appropriate backup method
  6025. // this type of work (copy/backup) would be a prelude to reindexing an index
  6026. // file or performing a pack on a data file since both of those routines
  6027. // overwrite existing data
  6028.  
  6029. COPYPACK CP;
  6030. LOCKPACK LP;
  6031. STATHANDLEPACK SHP;
  6032. STATDATAPACK SDP;
  6033. STATINDEXPACK SIP;
  6034.  
  6035. CHAR CopyOfIndexHdrName[260];
  6036. CHAR BackupDataName[260];
  6037.  
  6038. // Given a handle, find out its type and, if index, generate a copy
  6039. // of the index file's header, or if data, backup the entire data file.
  6040. // Files are locked to ensure that access if permissible.
  6041.  
  6042. SHP.func = STAT_HANDLE_XB;
  6043. SHP.handle = passedHandle;
  6044. rez = BULLET(&SHP);
  6045. if (SHP.ID==-1)
  6046.    puts("Handle is not a Bullet data or index file.  Use DosCopy() API call.");
  6047. else {
  6048.    if (SHP.ID==0) {
  6049.  
  6050.       // Since the copy takes place on open files, ensure a full-lock is in place
  6051.       // A shared lock is okay since this file is only read
  6052.  
  6053.       // locking the entire file also RELOADS the index header
  6054.  
  6055.       LP.func = LOCK_INDEX_XB;
  6056.       LP.handle = passedHandle;
  6057.       LP.xlMode = LOCK_SHARED;          // in bullet2.h
  6058.       rez = BULLET(&LP);
  6059.       if (rez) goto ErrorHandler;
  6060.  
  6061.       SIP.func = STAT_INDEX_XB;
  6062.       SIP.handle = passedHandle;
  6063.       rez = BULLET(&SIP);
  6064.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6065.  
  6066.       // SIP.filenamePtr -> pathname of this handle, from which you can
  6067.       // derive a suitable name for the index header written next -- in
  6068.       // case it's not obvious, this function is not part of Bullet
  6069.  
  6070.       DeriveSuitableName(SIP.filenamePtr,CopyOfIndexHdrName);
  6071.  
  6072.       CP.func = COPY_INDEX_HEADER_XB;
  6073.       CP.handle = passedHandle;
  6074.       CP.filenamePtr = CopyOfIndexHdrName;
  6075.       rez = BULLET(&CP);
  6076.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6077.  
  6078.       // unlocking also flushes the index header if not LOCK_SHARED (and if required)
  6079.  
  6080.       LP.func = UNLOCK_INDEX_XB;
  6081.       LP.handle = passedHandle;
  6082.       rez = BULLET(&LP);
  6083.       if (rez) goto ErrorHandler;
  6084.    }
  6085.    else {
  6086.  
  6087.       // locking the entire file also RELOADS the data header
  6088.  
  6089.       LP.func = LOCK_DATA_XB;
  6090.       LP.handle = passedHandle;
  6091.       LP.dlMode = LOCK_SHARED;
  6092.       LP.startRec = 0;                  // lock entire data file
  6093.       rez = BULLET(&LP);
  6094.       if (rez) goto ErrorHandler;
  6095.  
  6096.       SDP.func = STAT_DATA_XB;
  6097.       SDP.handle = passedHandle;
  6098.       rez = BULLET(&SDP);
  6099.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6100.  
  6101.       DeriveSuitableName(SDP.filenamePtr,BackupDataName);
  6102.  
  6103.       CP.func = BACKUP_FILE_XB;
  6104.       CP.handle = passedHandle;         // set to -passedHandle to skip memo backup
  6105.       CP.filenamePtr = BackupDataName;
  6106.       rez = BULLET(&CP);
  6107.       if (rez) goto ErrorHandler;       // must unlock file in handler
  6108.  
  6109.       // unlocking also flushes the data header if not LOCK_SHARED (and if required)
  6110.  
  6111.       LP.func = UNLOCK_DATA_XB;
  6112.       LP.handle = passedHandle;
  6113.       rez = BULLET(&LP);
  6114.       if (rez) goto ErrorHandler;
  6115.    }
  6116. }
  6117.  
  6118.  
  6119. ΓòÉΓòÉΓòÉ 10.5. Get Error Class ΓòÉΓòÉΓòÉ
  6120.  
  6121. #include "bullet2.h"
  6122.  
  6123. XERRORPACK XEP;                 // packs used here
  6124.  
  6125. // Bullet errors range from 8192 to 8999, any other return code
  6126. // indicates the error number was generated by OS/2 itself
  6127.  
  6128. if (rez < 8192) | (rez > 8999) {
  6129.    XEP.func = GET_ERROR_CLASS_XB;
  6130.    XEP.stat = rez;
  6131.    rez = BULLET(&XEP);
  6132.  
  6133.    // here XEP.errClass, .action, and .location are set
  6134.    // this call is the same as OS/2 API DosErrClass()
  6135.  
  6136.  
  6137. ΓòÉΓòÉΓòÉ 10.6. Query System Variables ΓòÉΓòÉΓòÉ
  6138.  
  6139. #include "bullet2.h"
  6140.  
  6141. QUERYSETPACK  QSP;              // packs used here
  6142.  
  6143. // Query a Bullet system variable
  6144.  
  6145. QSP.func = QUERY_SYSVARS_XB;
  6146. QSP.item = MUTEX_SEM_HANDLE;    // in bullet2.h
  6147. rez = BULLET(&QSP);
  6148. if (rez==0)
  6149.    printf("Bullet/2 mutex handle is %d\n",QSP.itemValue);
  6150.  
  6151.  
  6152. ΓòÉΓòÉΓòÉ 10.7. Set System Variables ΓòÉΓòÉΓòÉ
  6153.  
  6154. #include "bullet2.h"
  6155.  
  6156. QUERYSETPACK  QSP;              // packs used here
  6157.  
  6158. // Set a Bullet system variable
  6159.  
  6160. QSP.func = SET_SYSVARS_XB;
  6161. QSP.item = REINDEX_BUFFER_SIZE; // in bullet2.h
  6162. QSP.itemValue = 384*1024;       // set to 384KB
  6163. rez = BULLET(&QSP);
  6164. if (rez==0) {
  6165.    printf("Reindex buffer sized changed to 384K.\n");
  6166.    printf("Previous setting was %d.\n",QSP.itemValue);
  6167.  
  6168.    // For REINDEX_BUFFER_SIZE, a value of 0 represents 'autosize', for which
  6169.    // Bullet selects a minimum usuable size (often 144KB).  The minimum size
  6170.    // that you can use for REINDEX_BUFFER_SIZE is 48KB.
  6171.  
  6172.  
  6173. ΓòÉΓòÉΓòÉ 10.8. Set Dual-video Monitor ΓòÉΓòÉΓòÉ
  6174.  
  6175.  
  6176. // SET_DVMON_XB is not used in OS/2
  6177.  
  6178.  
  6179. ΓòÉΓòÉΓòÉ 10.9. Create, Open, and Close Data and Index Files ΓòÉΓòÉΓòÉ
  6180.  
  6181. #include "bullet2.h"
  6182.  
  6183. CREATEDATAPACK  CDP;
  6184. CREATEINDEXPACK CIP;
  6185. OPENPACK        OP;
  6186. HANDLEPACK      HP;             // packs used here
  6187.  
  6188. // create the data file
  6189.  
  6190. #pragma pack(1)         // ensure compiler does not pad Bullet-used structures
  6191.                         // (not needed here since all members are CHAR)
  6192.  
  6193. // generally, only left-justified strings should be 0-terminated, numbers or
  6194. // date fields should not be 0-terminated
  6195.  
  6196. typedef struct _RECTYPE {
  6197.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  6198.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  6199.  CHAR userScore[6];     // second field (also not 0T)
  6200. } RECTYPE;              // (total record length is 16 bytes)
  6201. RECTYPE ourRecord;
  6202.  
  6203. #pragma pack()
  6204.  
  6205. CHAR nameIX3[] = "INDEX.IX3";   // index pathname
  6206. CHAR keyExpression[] = "SSN";   // key is built from field named 'SSN'
  6207. ULONG indexID=0;                // handle of opened index file
  6208. CHAR keyBuffer[68];             // buffer to store/receive key values
  6209.  
  6210. CHAR nameData[] = "DATA.DBF";   // data pathname
  6211. ULONG dataID=0;                 // handle of opened data file
  6212. FIELDDESCTYPE fieldList[2];     // 2 fields used in data record (SSN and SCORE)
  6213.  
  6214. // the field descriptor info must have unused entries set to 0
  6215.  
  6216. memset(fieldList,0,sizeof(fieldList));  // init unused bytes to 0 (required)
  6217.  
  6218. // fill in the field descriptor info for the data file you want to create
  6219. // this descriptor must match the layout of ourRecord, above (ourRecord.tag
  6220. // is implicit and is not a formal field, and so is not in fieldList[])
  6221.  
  6222. strcpy(fieldList[0].fieldName, "SSN");  // field names must be upper-case
  6223. fieldList[0].fieldType = 'C';           // field types must be upper-case
  6224. fieldList[0].fieldLen = 9;              // * Note that the .fieldname here
  6225. fieldList[0].fieldDC = 0;               // * matches the keyExpression
  6226.  
  6227. strcpy(fieldList[1].fieldName, "SCORE");
  6228. fieldList[1].fieldType = 'C';
  6229. fieldList[1].fieldLen = 6;              // 6 is total size of field
  6230. fieldList[1].fieldDC = 0;
  6231.  
  6232. // Create the data file as defined in fieldList above
  6233. // To create only a DBF, set CDP.fileID=3
  6234. // To create both a DBF and a DBT memo file, set CDP.fileID=0x8B
  6235.  
  6236. CDP.func = CREATE_DATA_XB;
  6237. CDP.filenamePtr = nameData;
  6238. CDP.noFields = 2;
  6239. CDP.fieldListPtr = fieldList;
  6240. CDP.fileID = 3;
  6241. rez = BULLET(&CDP);
  6242. if (rez) {
  6243.    printf("Failed data file create.  Err: %d\n",rez);
  6244.    return(rez);
  6245. }
  6246.  
  6247. // Open the data file (required before creating an index file for it)
  6248.  
  6249. OP.func = OPEN_DATA_XB;
  6250. OP.filenamePtr = nameData;
  6251. OP.asMode = READWRITE | DENYNONE;
  6252. rez = BULLET(&OP);
  6253. if (rez) {
  6254.    printf("Failed data file open.  Err: %d\n",rez);
  6255.    return(rez);
  6256. }
  6257. dataID = OP.handle;
  6258.  
  6259. // Create an index file for the data file opened above.
  6260. // This example uses a simple primary key: the SSN field.
  6261. // Since it is assumed to be unique, DUPS_ALLOWED is not
  6262. // OR'ed with the .sortFunction.
  6263.  
  6264. CIP.func = CREATE_INDEX_XB;
  6265. CIP.filenamePtr = nameIX3;
  6266. CIP.keyExpPtr = keyExpression;
  6267. CIP.xbLink = dataID;            // the handle of the data file
  6268. CIP.sortFunction = ASCII_SORT;  // sort key by ASCII (fine for SSN ordering)
  6269. CIP.codePage = 0;               // use OS-default code page
  6270. CIP.countryCode = 0;            // use OS-default country code
  6271. CIP.collatePtr = NULL;          // no need for a special collate table
  6272. CIP.nodeSize = 512;             // 512-byte node size (or 1024, 2048 bytes)
  6273. rez = BULLET(&CIP);
  6274. if (rez) {
  6275.    printf("Failed index file create.  Err: %d\n",rez);
  6276.    return(rez);
  6277. }
  6278.  
  6279. // Open the index file (what we just created above).
  6280. // As with the index-create, the index-open requires the handle of the data
  6281. // file which this index file indexes.
  6282.  
  6283. OP.func = OPEN_INDEX_XB;
  6284. OP.filenamePtr = nameIX3;
  6285. OP.asMode = READWRITE | DENYNONE;
  6286. OP.xbLink = dataID;
  6287. rez = BULLET(&OP);
  6288. if (rez) {
  6289.    printf("Failed index file open.  Err: %d\n",rez);
  6290.    return(rez);
  6291. }
  6292. indexID = OP.handle;
  6293.  
  6294. // at this point, both the data and index files are open and accessible
  6295.  
  6296. // |
  6297. // | do work as required, then, when done, close them
  6298. // |
  6299.  
  6300. if (indexID) {
  6301.    HP.func = CLOSE_INDEX_XB;
  6302.    HP.handle = indexID;
  6303.    rez = BULLET(&HP);
  6304.    if (rez)
  6305.       printf("Failed index file close.  Err: %d\n",rez);
  6306. }
  6307.  
  6308. if (dataID) {
  6309.    HP.func = CLOSE_DATA_XB;
  6310.    HP.handle = dataID;
  6311.    rez = BULLET(&HP);
  6312.    if (rez)
  6313.       printf("Failed data file close.  Err: %d\n",rez);
  6314. }
  6315.  
  6316.  
  6317. ΓòÉΓòÉΓòÉ 10.10. Read Data and Index Header ΓòÉΓòÉΓòÉ
  6318.  
  6319. #include "bullet2.h"
  6320.  
  6321. HANDLEPACK HP;                  // packs used here
  6322.  
  6323. // Since it is recommended that a full-lock be in force before reloading
  6324. // data or index headers, and since performing a full lock from BULLET does
  6325. // itself reload the header, this routine would not normally be used.
  6326. // However, if you are doing your own locking, then you need to call this.
  6327.  
  6328. rez = YourExternalControlLockRoutine;  // so you have your own locks...
  6329.  
  6330. if (rez==0) {
  6331.  
  6332.    if (youWantDataReload) {
  6333.       HP.func = READ_DATA_HEADER_XB;
  6334.       HP.func = dataID;
  6335.    }
  6336.    else {
  6337.       HP.func = READ_INDEX_HEADER_XB;
  6338.       HP.func = indexID;
  6339.    }
  6340.    rez = BULLET(&HP);
  6341.  
  6342.    // since locked, release lock regardless rez value
  6343.  
  6344.    rez2 = YourExternalControlUnlockRoutine;
  6345. }
  6346.  
  6347. // Be sure to read the explanation above
  6348.  
  6349.  
  6350. ΓòÉΓòÉΓòÉ 10.11. Flush Data and Index Header ΓòÉΓòÉΓòÉ
  6351.  
  6352. #include "bullet2.h"
  6353.  
  6354. HANDLEPACK HP;                  // packs used here
  6355.  
  6356. // While BULLET automatically flushes data and index info whenever
  6357. // a BULLET file is unlocked from a full-lock (and if it
  6358. // is needed), you may to flush more frequently.
  6359.  
  6360. // It is recommended that you have a full-lock on the file before
  6361. // flushing.  In normal use, you would always have a full-lock when
  6362. // writing to a file (the only time you need to flush is if the file
  6363. // has been written to).  If you are, for whatever reason, keeping
  6364. // the file locked, and are updating it repeatedly, and have no
  6365. // intention of unlocking (and thereby flushing it) any time soon,
  6366. // you may do a manual flush to ensure that the disk image matches
  6367. // the memory image (in case the power goes out and you have no UPS)
  6368.  
  6369. if (youWantDataFlush) {
  6370.    HP.func = FLUSH_DATA_HEADER_XB;
  6371.    HP.func = dataID;
  6372. }
  6373. else {
  6374.    HP.func = FLUSH_INDEX_HEADER_XB;
  6375.    HP.func = indexID;
  6376. }
  6377. rez = BULLET(&HP);
  6378.  
  6379. // Only if the file has been changed does a flush actually write to disk.
  6380. // You should have an exclusive full-lock; a shared full-lock cannot be
  6381. // used since a shared lock does not allow writing to the file.
  6382.  
  6383.  
  6384. ΓòÉΓòÉΓòÉ 10.12. Copy (Add) a Subset of Records to a New File ΓòÉΓòÉΓòÉ
  6385.  
  6386. #include "bullet2.h"
  6387.  
  6388. ACCESSPACK APo;                 // used when accessing original
  6389. ACCESSPACK APn;                 // used when accessing new
  6390. COPYPACK   CP;
  6391. HANDLEPACK HP;
  6392. OPENPACK   OP;                  // packs used here
  6393.  
  6394. RECTYPE ourRecord;              // as defined in Create example
  6395.  
  6396. // Assume an open, locked DBF data file, handle in dataID, and that you
  6397. // want to copy those records that are marked as deleted, one at a time, to a
  6398. // new file, prior to packing the database.  An extension to this procedure is
  6399. // to access each record in key order, and to copy each record to the new
  6400. // file, thereby giving a SORTED data file (also known as a clustered file).
  6401. // The lock must be a full-lock, but may be a shared full-lock.  A ZAP is done
  6402. // on the new file if the copy did not complete as expected.
  6403.  
  6404. // No indexed access is used in this example.
  6405.  
  6406. CP.func = COPY_DATA_HEADER_XB;
  6407. CP.handle = dataID;             // dataID is the original data file handle
  6408. CP.filenamePtr = "DELRECS.DBF"; // new file for deleted records
  6409. rez = BULLET(&CP);
  6410. if (rez) {
  6411.    printf("Failed header copy.  Err: %d\n",rez);
  6412.    return(rez);
  6413. }
  6414.  
  6415. // DELRECS.DBF now is exactly like the original, but has 0 records.  Since
  6416. // we're building this file, open it for exclusive use (DENYREADWRTE) --
  6417. // this is different from using the LOCK_XB routines since the lock is done
  6418. // at the file open level (no other process may even open it), whereas
  6419. // the LOCK_XB routines are at the access level (other processes may
  6420. // open the file, but may or may not access it).  You could instead use
  6421. // LOCK_DATA_XB for an exclusive full-lock, but this is simpler.
  6422.  
  6423. OP.func = OPEN_DATA_XB;
  6424. OP.filenamePtr = "DELRECS.DBF";         // open it
  6425. OP.asMode = READWRITE | DENYREADWRITE;  // for exclusive use
  6426. rez = BULLET(&OP);
  6427. if (rez) {
  6428.    printf("Failed new file open.  Err: %d\n",rez);
  6429.    return(rez);
  6430. }
  6431.  
  6432. // Now have two files open:  the original, with all the records, and
  6433. // the new, with no records.  The procedure here is to get all original
  6434. // records, check each for being deleted, if so, add that record (copy it)
  6435. // to the new file.  After copying, the original file is packed so that
  6436. // all deleted records are removed.  Then an index to it is reindexed.
  6437.  
  6438. // most BULLET pack members will be invariant within loops... (low overhead!)
  6439.  
  6440. APn.func = ADD_RECORD_XB;       // AccessPack for the new file
  6441. APn.handle = OP.handle;         // the handle just opened above
  6442. APn.recPtr = &ourRecord;
  6443.  
  6444. APo.func = GET_RECORD_XB;       // AccessPack for the original file
  6445. APo.handle = dataID;
  6446. APo.recNo = 1;                  // start at the first record
  6447. APo.recPtr = &ourRecord;        // read data into this
  6448. rez = BULLET(&APo);             // read the first data record
  6449.  
  6450. while (rez==0) {
  6451.  
  6452.    // check if this record is deleted, if so copy it else continue
  6453.  
  6454.    if (ourRecord.tag = '*') {
  6455.       rez = BULLET(&APn);       // add it to the new file
  6456.       if (rez) break;
  6457.       // here APn.recNo is the record number used for the just-added record
  6458.    }
  6459.  
  6460.    // This while() loop could have been a for() loop if we had used
  6461.    // STAT_DATA_XB to get the number of records, but in this example,
  6462.    // the original file is read until EXB_BAD_RECNO is returned,
  6463.    // indicating that the last record has been passed.
  6464.  
  6465.    APo.recNo++;                 // get next original record
  6466.    rez = BULLET(&APo);          // everything else is already setup
  6467. }
  6468.  
  6469. // the expected rez here is EXB_BAD_RECNO, any other then quit
  6470.  
  6471. if (rez != EXB_BAD_RECNO) {
  6472.     printf("Failed the while() loop, ZAPing new file.  Err: %d\n",rez);
  6473.  
  6474.     // As an example, if the copy failed to complete as expected, the
  6475.     // new file is ZAP'ed, removing any records that may have been copied
  6476.     // up to the point that the error occurred -- investigate failure and
  6477.     // restart process (you may want to just delete, rather than ZAP/CLOSE).
  6478.  
  6479.     HP.func = ZAP_DATA_HEADER_XB;
  6480.     HP.handle = APn.handle;     // the new file handle
  6481.     rez2 = BULLET(&HP);         // using 'rez2' to preserve initial error code
  6482.     if (rez2)
  6483.        printf("Failed ZAP!  Err: %d\n",rez2);
  6484.  
  6485.     HP.func = CLOSE_DATA_XB;    // close
  6486.     rez2 = BULLET(&HP);
  6487.     if (rez2)
  6488.        printf("Failed CLOSE!  Err: %d\n",rez2);
  6489.  
  6490.     return(rez);                // return initial error code
  6491. }
  6492.  
  6493. // done with the new file
  6494. // it contains all the records in the original marked as deleted
  6495.  
  6496. HP.func = CLOSE_DATA_XB;        // always use the correct pack for the routine
  6497. HP.handle = APn.handle;         // -- do not try to use AP when closing a file
  6498. rez = BULLET(&HP);
  6499. if (rez) return(rez);
  6500.  
  6501. // Pack the original data file, now that we've "saved" the delete-marked recs.
  6502. // Note: You may want to use BACKUP_XB before using this next routine
  6503. // in case a serious error occurs.  BULLET packs in place!  Also, before
  6504. // packing, memos belonging to records about to be deleted should have
  6505. // have been deleted before packing.  Neither is shown here.
  6506.  
  6507. APo.func = PACK_RECORDS_XB;
  6508. rez = BULLET(&APo);
  6509. if (rez==0) {
  6510.  
  6511.    // After a pack, you must reindex any related index files.
  6512.    // Assume here one index file, handle in indexID
  6513.  
  6514.    APo.func = REINDEX_XB;
  6515.    APo.handle = indexID;
  6516.    rez = BULLET(&APo);
  6517.    if (rez)
  6518.       printf("Failed reindex.  Err: %d\n",rez);
  6519. }
  6520. else {
  6521.    printf("Failed packed!  Recommend restore from backup.  Err: %d\n",rez);
  6522.    printf("Note: Unless error is known to not be severe.\n");
  6523. }
  6524.  
  6525. // Here and rez==0 then everything went as planned.
  6526.  
  6527. return(rez);
  6528.  
  6529.  
  6530. ΓòÉΓòÉΓòÉ 10.13. Zap Index File ΓòÉΓòÉΓòÉ
  6531.  
  6532. #include "bullet2.h"
  6533.  
  6534. HANDLEPACK HP;                  // packs used here
  6535.  
  6536. // Since BULLET reindexes in place, there's typically no need to use
  6537. // ZAP to reduce disk requirements (there won't be two separate file
  6538. // spaces since the reindex copies right over the old key data).
  6539.  
  6540. HP.func = ZAP_INDEX_HEADER_XB;
  6541. HP.handle = indexToZap;
  6542. rez = BULLET(&HP);
  6543. if (rez) return(rez);
  6544.  
  6545.  
  6546. ΓòÉΓòÉΓòÉ 10.14. Get Descriptor, Using a DBF Not Created by Bullet ΓòÉΓòÉΓòÉ
  6547.  
  6548. #include <os2.h>
  6549. #include <stdio.h>
  6550. #include <stdlib.h>
  6551. #include <string.h>
  6552.  
  6553. #include "bullet2.h"
  6554.  
  6555. int main(int argc,char *argv[]) {
  6556.  
  6557. INITPACK IP;
  6558. EXITPACK EP;
  6559. DESCRIPTORPACK DP;
  6560. OPENPACK OP;
  6561. HANDLEPACK HP;
  6562. STATDATAPACK SDP;
  6563. ACCESSPACK AP;          // packs used here
  6564.  
  6565. PFIELDDESCTYPE fieldDescPtr;    // pointer to field descriptor base allocation
  6566. PFIELDDESCTYPE fdPtr;           // roving pointer to any field's descriptor
  6567.  
  6568. CHAR dataRec[8192];     // 'unknown' record layout since reading "any" DBF
  6569. CHAR  fmt[32];          // printf() fmt string for on-the-fly formatting
  6570. ULONG dataID;           // handle of DBF
  6571. LONG  recNo;            // loop counter
  6572. BYTE  fldNo;            // loop counter2
  6573. int   rez;              // primary op return code
  6574. int   rez2;             // secondary op return code (so to perserve primary rc)
  6575.  
  6576. if (argc < 2) {
  6577.    puts("Use: C>progname anyfile.dbf");
  6578.    return(1);
  6579. }
  6580.  
  6581. // init Bullet
  6582.  
  6583. IP.func = INIT_XB;
  6584. IP.JFTsize = 20;                // 20 handles is all we need here
  6585. rez = BULLET(&IP);
  6586. if (rez!=0) {
  6587.    printf("INIT_XB failed: %d\n",rez);
  6588.    return(1);
  6589. }
  6590.  
  6591. // open existing DBF as named in command line
  6592.  
  6593. OP.func = OPEN_DATA_XB;
  6594. OP.filenamePtr = argv[1];
  6595. OP.asMode = READWRITE | DENYNONE;
  6596. rez = BULLET(&OP);
  6597. if (rez==0) {
  6598.  
  6599.    dataID = OP.handle;
  6600.  
  6601.    SDP.func = STAT_DATA_XB;
  6602.    SDP.handle = dataID;
  6603.    rez = BULLET(&SDP);
  6604.    if (rez==0) {
  6605.  
  6606.       // allocate field descriptors needed (SDP.fields is number needed)
  6607.       // calloc() used since 0-filled storage is required
  6608.  
  6609.       fieldDescPtr = calloc(SDP.fields,sizeof(FIELDDESCTYPE));
  6610.  
  6611.       if (fieldDescPtr != NULL) {
  6612.  
  6613.          fdPtr = fieldDescPtr;          // fdPtr->each descriptor
  6614.  
  6615.          // read each field descriptor from Bullet, storing to our program
  6616.          // show each for display
  6617.  
  6618.          //      1234567890-123456789-123456789-12345
  6619.          printf("FLD#   FIELDNAME  T  LEN.DEC  OFFSET\n");
  6620.  
  6621.          DP.func = GET_DESCRIPTOR_XB;
  6622.          DP.handle = dataID;
  6623.          for (fldNo=1;fldNo <= SDP.fields;fldNo++) {
  6624.  
  6625.             DP.fieldNumber = fldNo;
  6626.             rez = BULLET(&DP);
  6627.             if (rez==0) {
  6628.  
  6629.                strcpy(fdPtr->fieldName, DP.FD.fieldName);
  6630.                fdPtr->fieldType = DP.FD.fieldType;
  6631.                fdPtr->fieldLen = DP.FD.fieldLen;
  6632.                fdPtr->fieldDC = DP.FD.fieldDC;
  6633.                fdPtr->fieldDA = DP.fieldOffset;
  6634.                printf("%3u   %-10s  %c  %3u.%1u     %4u\n",
  6635.                   fldNo,
  6636.                   fdPtr->fieldName,
  6637.                   fdPtr->fieldType,
  6638.                   (ULONG) fdPtr->fieldLen,
  6639.                   (ULONG) fdPtr->fieldDC,
  6640.                   fdPtr->fieldDA);
  6641.                fdPtr++;                 // next field descriptor
  6642.             }
  6643.             else
  6644.                break;
  6645.          }
  6646.  
  6647.          // An interesting item above is where fdPtr->fieldDA is set to
  6648.          // DP.fieldOffset.  fieldDA is a run-time storage area that in
  6649.          // dBASE is used to directly access the field (DA="direct access").
  6650.          // It has no meaning except for that particular run (it is a memory
  6651.          // address). In this program example I use it to store the offset
  6652.          // of the field, relative the start of the record buffer (where the
  6653.          // tag byte = offset 0).  You could just as easily use some of the
  6654.          // 12 reserved bytes left over in the descriptor, as I do for the
  6655.          // alternate field length.  But, since fieldDA is already there, and
  6656.          // not used otherwise, it makes sense to use it.
  6657.  
  6658.          // Now have all we need to know about the DBF fields, having just
  6659.          // read and stored the field descriptors.  For this example, we
  6660.          // grab the first nine records and spit them out, by field, in record
  6661.          // number order (no indexing used).
  6662.  
  6663.          if (SDP.records != 0) {
  6664.  
  6665.             AP.func = GET_RECORD_XB;
  6666.             AP.handle = dataID;
  6667.             AP.recPtr = &dataRec;
  6668.  
  6669.             for (recNo=1;recNo <= 9; recNo++) {
  6670.  
  6671.                printf("\nrecNo %u: ",recNo);    // show line number
  6672.                AP.recNo = recNo;                // get this record #...
  6673.                rez = BULLET(&AP);               // ...to dataRec buffer
  6674.                if (rez==0) {
  6675.                   printf("%.1s ",(CHAR *) dataRec); // show if deleted or not
  6676.  
  6677.                   fdPtr = fieldDescPtr; // fdPtr->first field descriptor
  6678.  
  6679.                   for (fldNo=1;fldNo <= SDP.fields;fldNo++) {
  6680.  
  6681.                      // No special formatting is done on this output for this
  6682.                      // example -- since standard DBF data is always in pure
  6683.                      // ASCII form, all is printable.
  6684.  
  6685.                      switch (fdPtr->fieldType) {
  6686.                      case 'C':  // text
  6687.                      case 'D':  // date, show as-is
  6688.                      case 'L':  // logical, show as-is
  6689.                      case 'M':  // memo field (block number in ASCII)
  6690.                      case 'N':  // numeric (ASCII)
  6691.  
  6692.                         // make fmt[] string like this: "%xx.xxs"
  6693.                         // where xx is field length for this field
  6694.  
  6695.                         sprintf(fmt,"%%-%i.%is ",
  6696.                                 fdPtr->fieldLen,
  6697.                                 fdPtr->fieldLen);
  6698.  
  6699.                         // fdPtr->fieldDA=offset of the field within the record
  6700.                         // so it plus dataRec (buffer base) results in the
  6701.                         // offset of the current field we are processing
  6702.  
  6703.                         printf(fmt,dataRec+fdPtr->fieldDA);
  6704.                         break;
  6705.                      default:
  6706.                         printf("\nUnknown field type: %c\n",fdPtr->fieldType);
  6707.                      } // switch
  6708.  
  6709.                      fdPtr += 1;                  // next field's descriptor
  6710.  
  6711.                   } // for fields
  6712.                } // if record read
  6713.  
  6714.                else {
  6715.                   if (rez==EXB_BAD_RECNO)       // if < for-count records in DBF
  6716.                      rez=0;                     // then would get this error
  6717.                   else
  6718.                      printf("Failed GET_RECORD_XB, err: %d\n",rez);
  6719.                   break;                        // break for any ELSE case
  6720.                }
  6721.  
  6722.             } // for records
  6723.             if (rez==0) printf("\nDone.\n"); // all FOR recs done
  6724.          }
  6725.          else
  6726.             printf("No records in file\n");
  6727.  
  6728.          free(fieldDescPtr);
  6729.       }
  6730.       else
  6731.          printf("calloc failed!\n");
  6732.    }
  6733.    else
  6734.       printf("STAT_DATA_XB failed: %d\n",rez);
  6735.  
  6736.    HP.func = CLOSE_DATA_XB;
  6737.    HP.handle = dataID;
  6738.    rez2 = BULLET(&HP);
  6739. }
  6740. else
  6741.    printf("OPEN_DATA_XB failed: %d\n",rez);
  6742.  
  6743. EP.func = EXIT_XB;
  6744. rez2=BULLET(&EP);
  6745.  
  6746. printf("\nPress ENTER to exit");
  6747. getchar();
  6748. if (rez==0) rez=rez2;  // rez is more important, but if 0 use rez2 result
  6749. return(rez);
  6750. }
  6751.  
  6752. The above is a complete program.  Running it against a sample DBF results in 
  6753. the following output: 
  6754.  
  6755. FLD#   FIELDNAME  T  LEN.DEC  OFFSET
  6756.   1   SSN         C    9.0        1
  6757.   2   LNAME       C   16.0       10
  6758.   3   FNAME       C   16.0       26
  6759.   4   HIRED       D    8.0       42
  6760.   5   DEPT_ID     C    6.0       50
  6761.  
  6762. recNo 1:   465309999 Que              Barbie           19900131 BOSS
  6763. recNo 2:   445038888 Stewart          Jackie           19910228 ACC
  6764. recNo 3:   760443232 Whitman          Kelly            19920414 HUM
  6765. recNo 4:   845309944 Beatty           Leslie           19940122 PRG
  6766. recNo 5:   555033388 Jasper           Amy              19930230 PRG
  6767. recNo 6:   430443222 Hauntos          Poco             19920414 PRG
  6768. recNo 7:   365502949 Hopkins          Lisa             19910121 PRG
  6769. recNo 8:   685733868 Leonard          Rosina           19850218 PRG
  6770. recNo 9:   500945242 Morton           Holly            19950406 PHY
  6771. Done.
  6772.  
  6773. Press ENTER to exit
  6774.  
  6775.  
  6776. ΓòÉΓòÉΓòÉ 10.15. Update a Data Record ΓòÉΓòÉΓòÉ
  6777.  
  6778. #include "bullet2.h"
  6779.  
  6780. ACCESSPACK AP;                  // packs used here
  6781.  
  6782. typedef struct _RECTYPE {
  6783.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  6784.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  6785.  CHAR userScore[6];     // second field (also not 0T)
  6786. } RECTYPE;              // (total record length is 16 bytes)
  6787. RECTYPE ourRecord;
  6788.  
  6789. // This excerpt demonstrates how to update (change) a record.
  6790. // The idea is to get the current contents of a record (by record
  6791. // number since no index is used for this update routine), change
  6792. // what needs changing, then write it back.  Under no circumstances
  6793. // should you change any field that is used as a key by an index, or
  6794. // as a foreign key, or in any other way removes the referential
  6795. // integrity of the database.  If you need to change a key field, then
  6796. // you must use UPDATE_XB.
  6797.  
  6798. AP.func = GET_RECORD_XB;
  6799. AP.handle = dataID;
  6800. AP.recNo = recordToUpdate;
  6801. AP.recPtr = &ourRecord;
  6802. rez = BULLET(&AP);
  6803. if (rez) return(rez);
  6804.  
  6805. // ourRecord has data stored at record number recordToUpdate -- since
  6806. // userScore is not used as a key field, this routine may be used to
  6807. // modify the contents of that field.  Since numbers are stored as ASCII
  6808. // text in compatible DBF files, must convert to binary, perform needed
  6809. // math, then convert back to text:
  6810.  
  6811. t = atol(ourRecord.userScore);
  6812. t = t + ClassCurve;             // increase each score by curve value
  6813. sprintf(ourRecord.userScore,"%6.6u",t)
  6814.  
  6815. AP.func = UPDATE_RECORD_XB;     // other AP values already set up from GET
  6816. rez = BULLET(&AP);              // write out the record with the new score
  6817. if (rez) return(rez);
  6818.  
  6819.  
  6820. ΓòÉΓòÉΓòÉ 10.16. Delete, Undelete, 'Debump' a Data Record ΓòÉΓòÉΓòÉ
  6821.  
  6822. #include "bullet2.h"
  6823.  
  6824. ACCESSPACK AP;                  // packs used here
  6825.  
  6826. // delete or undelete or remove (debump)
  6827.  
  6828. switch(*requestMsg) {
  6829. case 'delete':
  6830.    AP.func = DELETE_RECORD_XB;  // places a '*' in .tag byte
  6831.    break;
  6832. case 'undelete':
  6833.    AP.func = UNDELETE_RECORD_XB; // places a SPACE in .tag byte
  6834.    break;
  6835. case 'debump':
  6836.    AP.func = DEBUMP_RECORD_XB;  // physically removes record from file, but
  6837.    break;                       // fails if AP.recNo is not last record number
  6838. }
  6839.  
  6840. AP.handle = dataID;             // same for all three
  6841. AP.recNo = recordNumber;
  6842. rez = BULLET(&AP);
  6843. return(rez);
  6844.  
  6845.  
  6846. ΓòÉΓòÉΓòÉ 10.17. Reading Memo Records ΓòÉΓòÉΓòÉ
  6847.  
  6848. #include "bullet2.h"
  6849.  
  6850. ACCESSPACK AP;
  6851. LOCKPACK LP;
  6852. MEMODATAPACK MDP;       // packs used here
  6853.  
  6854. typedef struct _RECTYPE {
  6855.  CHAR tag;              // record tag, init to SPACE, '*' means deleted
  6856.  CHAR userSSN[9];       // first field in DBF (not 0-terminated in this case)
  6857.  CHAR userMemo[10];     // second field (also not 0T), is memo field type
  6858. } RECTYPE;
  6859. RECTYPE someRecord;
  6860.  
  6861. // a minimum shared record lock is required on the DBF record that owns
  6862. // memoNumber in this example, since only reading of the single memo is done
  6863.  
  6864. LP.func = LOCK_DATA_XB;
  6865. LP.handle = dataID;
  6866. LP.dlMode = LOCK_SHARED;        // only reading here, shared record lock is okay
  6867. LP.recStart = recordToGet;      // lock this record
  6868. LP.recCount = 1;                // and only this record
  6869. rez = BULLET(&LP);
  6870. if (rez) return(rez);
  6871.  
  6872. // hereafter, must unlock before exiting
  6873.  
  6874. AP.func = GET_RECORD_XB;
  6875. AP.handle = dataID;
  6876. AP.recNo = recordToGet;
  6877. AP.recPtr = &someRecord;        // load someRecord with data on disk
  6878. rez = BULLET(&AP);
  6879. if (rez) return(rez);           // UNLOCK! before doing this exit
  6880.  
  6881. memoNumber = atol(someRecord.userMemo); // the memo number (0 if none)
  6882.  
  6883. // this code reads the number of data bytes in the memo and allocates a
  6884. // run-time buffer to read that memo into
  6885.  
  6886. MDP.func = GET_MEMO_SIZE_XB;
  6887. MDP.dbfHandle = dataID;         // handle of the DBF this memo belongs to
  6888. MDP.memoNo = memoNumber;        // memo number to get size of (1=first)
  6889. rez = BULLET(&MDP);             // (returns an error if memoNumber is 0)
  6890. if (rez==0) {
  6891.  
  6892.    // BULLET does maintain 0-sized memo records, so you may want to check
  6893.    // if MDP.memoBytes from GET_MEMO_SIZE_XB is 0, and skip processing if so
  6894.  
  6895.    memoBytesToRead = MDP.memoBytes;         // since overwritten by next call
  6896.    memoBufferPtr = malloc(memoBytesToRead); // assuming you want it all at once
  6897.  
  6898.    if (memoBufferPtr) {
  6899.  
  6900.       MDP.func = GET_MEMO_XB;
  6901.       MDP.dbfHandle = dataID;      // same as before, as is .memoNo
  6902.       MDP.memoNo = memoNumber;
  6903.       MDP.memoPtr = memoBufferPtr; // memo disk data is loaded into this buffer
  6904.       MDP.memoOffset = 0;          // read from very first memo data byte
  6905.       MDP.memoBytes = memoBytesToRead;
  6906.  
  6907.       // MDP.memoBytes is already set to the total data size -- you may read
  6908.       // fewer bytes, and you may use .offset to move through the memo data
  6909.       // chunks at a time, rather than all at once -- the above simply reloads
  6910.       // it with the same count, since here memoBytesToRead==MDP.memoBytes
  6911.  
  6912.       rez = BULLET(&MDP);          // returns with MDP.memoBytes= bytes read
  6913.       if (rez==0) {
  6914.  
  6915.          // if (MDP.memoBytes != memoBytesToRead)
  6916.          //   printf("Could not read all bytes requested - probably at end of memo\n");
  6917.          // above would not happen in this case since the exact size was requested
  6918.  
  6919.          // process as required (here passes buffer ptr and bytes actually read)
  6920.  
  6921.          DoWhatYouWillWithThisMemoData(memoBufferPtr,MDP.memoBytes);
  6922.       }
  6923.       free(memoBufferPtr);
  6924.    }
  6925.    else rez=8;  // malloc failed, return 8=not enough memory
  6926. }
  6927.  
  6928. LP.func = UNLOCK_DATA_XB;
  6929. LP.handle = dataID;
  6930. LP.recStart = recordToGet;      // unlock this record
  6931. LP.recCount = 1;                // and only this record
  6932. rez2 = BULLET(&LP);
  6933.  
  6934. if (rez==0) rez=rez2;
  6935. return(rez);
  6936.  
  6937.  
  6938. ΓòÉΓòÉΓòÉ 10.18. Add, Update, Delete a Memo Record ΓòÉΓòÉΓòÉ
  6939.  
  6940. #include "bullet2.h"
  6941.  
  6942. ACCESSPACK AP;
  6943. LOCKPACK LP;
  6944. MEMODATAPACK MDP;       // packs used here
  6945.  
  6946. typedef struct _RECTYPE {
  6947.  CHAR tag;
  6948.  CHAR userSSN[9];
  6949.  CHAR userMemo[10];
  6950. } RECTYPE;
  6951. RECTYPE someRecord;
  6952.  
  6953. // an exclusive lock is required on the DBF file that owns this memo file
  6954. // since writing is done to the memo file (memo file header, especially)
  6955.  
  6956. LP.func = LOCK_DATA_XB;
  6957. LP.handle = dataID;
  6958. LP.dlMode = LOCK_EXCLUSIVE;     // writing here, exclusive full lock required
  6959. LP.recStart = 0;                // lock all
  6960. rez = BULLET(&LP);
  6961. if (rez) return(rez);
  6962.  
  6963. // hereafter, must unlock before exiting
  6964.  
  6965. AP.func = GET_RECORD_XB;
  6966. AP.handle = dataID;
  6967. AP.recNo = recordToGet;
  6968. AP.recPtr = &someRecord;        // load someRecord with data on disk
  6969. rez = BULLET(&AP);
  6970. if (rez) return(rez);           // UNLOCK! before doing this exit
  6971.  
  6972. memoNumber = atol(someRecord.userMemo); // the memo number (0 if none)
  6973.  
  6974. // if there is no current memo, this example adds one
  6975. // if there is, this example updates it by:
  6976. //   - changing the first 16 bytes to "Kilroy was here."
  6977. //   - adding the text "Was updated." to the end of the current memo data
  6978. // the example then deletes the memo
  6979.  
  6980. CHAR kilroyStr[] = "Kilroy was here.";
  6981. CHAR updateStr[] = "Was updated.";
  6982. CHAR newStr[] = "New.";
  6983.  
  6984. if (memoNumber) {
  6985.  
  6986.    // modify the current memo -- first, the text "Kilroy was here." is
  6987.    // placed at the start of the memo, then the memo size is gotten (in
  6988.    // case the original memo size were less than the size of "Kilroy...").
  6989.  
  6990.    MDP.func = UPDATE_MEMO_XB;
  6991.    MDP.dbfHandle = dataID;      // handle of the DBF this memo belongs to
  6992.    MDP.memoNo = memoNumber;     // memo number to update (1=first)
  6993.    MDP.memoPtr = kilroyStr;     // data to write
  6994.    MDP.memoOffset = 0;          // start write at first byte of memo
  6995.    MDP.memoBytes = strlen(kilroyStr); // bytes to write
  6996.    rez = BULLET(&MDP);
  6997.  
  6998.       // the first 16 bytes of the memo now say kilroyStr (overwrote what was there)
  6999.       // the memo size changes only if the original memo was < 16 bytes, in
  7000.       // which case the size is now 16
  7001.  
  7002.    if (rez==0) {
  7003.       printf("%s overwrote first 16 bytes\n",kilroyStr);
  7004.  
  7005.       // must check if the update resulted in a new memo block being
  7006.       // used (if the update required more allocation blocks), and if
  7007.       // so must update the DBF field storing the memo number
  7008.       // MDP.memoNo is the memo number returned, memoNumber the original number
  7009.  
  7010.       // IT CAN BE ASSUMED IN THIS PARTICULAR example that this will never
  7011.       // be needed since the update modified the first 16 bytes of the
  7012.       // memo only, and so would never have required any more blocks --
  7013.       // however, unless you know before-hand that the update will not need
  7014.       // more allocation blocks (not difficult, if you know the block size,
  7015.       // overhead bytes (8), and your offset and bytes to write), it should
  7016.       // be checked -- hint: as with all Bullet routines, the idea is to
  7017.       // wrap up these separate operations into nice, neat callable routines
  7018.       // that take care of your particular need; there are no doubt 1000s of
  7019.       // variations -- pick one you can deal with.
  7020.  
  7021.       if (MDP.memoNo != memoNumber) {
  7022.          sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7023.          memoNumber = MDP.memoNo;       // set original to new for next update
  7024.  
  7025.          // rather than updating here, and possibly again below, you
  7026.          // may elect to set a flag and then do the DBF update at the end, once
  7027.          // again -- this updates the _data_ record, in the DBF file:
  7028.  
  7029.          AP.func = UPDATE_RECORD_XB;    // this updates the data record only
  7030.          AP.handle = dataID;
  7031.          AP.recNo = recordToGet;
  7032.          AP.recPtr = &someRecord;       // write the new data
  7033.          rez = BULLET(&AP);
  7034.          if (rez) return(rez);          // UNLOCK! before doing this exit
  7035.       }
  7036.  
  7037.       MDP.func = GET_MEMO_SIZE_XB;  // other MDP members already set above
  7038.       rez = BULLET(&MDP);
  7039.       if (rez=0) {              // size of memo is at least 16 (from kilroyStr)
  7040.                                 // but may be bigger if was bigger before
  7041.          MDP.func = UPDATE_MEMO_XB;
  7042.          MDP.memoPtr = updateStr;
  7043.  
  7044.          // the current memo size is used as the offset for the appending of
  7045.          // the updateStr bytes (offset is 0-based, so using MDP.memoBytes
  7046.          // results in the offset being the current size + 1)
  7047.  
  7048.          MDP.memoOffset = MDP.memoBytes;
  7049.          MDP.memoBytes = strlen(updateStr);
  7050.          rez = BULLET(&MDP);   // returns with MDP.memoNo
  7051.                                // bytes written==MDP.memoBytes always
  7052.          if (rez==0)
  7053.  
  7054.             printf("%s appended to memo\n",updateStr);
  7055.             // _minimum_ memo contents now is kilroyStr plus updateStr
  7056.             // more if original memo was > 16 bytes
  7057.  
  7058.             if (MDP.memoNo != memoNumber) {
  7059.                sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7060.                AP.func = UPDATE_RECORD_XB;         //
  7061.                AP.handle = dataID;                 // as explained above
  7062.                AP.recNo = recordToGet;             //
  7063.                AP.recPtr = &someRecord;
  7064.                rez = BULLET(&AP);
  7065.                if (rez) return(rez);    // actually must unlock before exit!
  7066.             }
  7067.          } // memo update #2 failed
  7068.       } // memo size failed
  7069.    }
  7070.    else
  7071.       printf("update failed, err: %d\n",rez); // disk full probably
  7072. }
  7073. else {
  7074.  
  7075.    // no current memo, add one
  7076.  
  7077.    MDP.func = ADD_MEMO_XB;
  7078.    MDP.dbfHandle = dataID;      // handle of the DBF this memo belongs to
  7079.    MDP.memoPtr = newStr;        // data to write
  7080.    MDP.memoBytes = strlen(newStr); // bytes to write
  7081.    rez = BULLET(&MDP);
  7082.    if (rez==0) {
  7083.       sprintf(someRecord.userMemo,"%10.10u",MDP.memoNo)
  7084.       AP.func = UPDATE_RECORD_XB;         //
  7085.       AP.handle = dataID;                 // as explained above
  7086.       AP.recNo = recordToGet;             //
  7087.       AP.recPtr = &someRecord;
  7088.       rez = BULLET(&AP);
  7089.    }
  7090.    else
  7091.      printf("add failed, err: %d\n",rez);
  7092. }
  7093.  
  7094. // delete the memo just operated on
  7095.  
  7096. if (rez==0) {
  7097.  
  7098.    MDP.func = DELETE_MEMO_XB;
  7099.    // MDP.memoNo is already set
  7100.    rez = BULLET(&MDP);
  7101.    if (rez==0) {
  7102.       strcpy(someRecord.userMemo,"          ");// DBF memo field to all spaces
  7103.       AP.func = UPDATE_RECORD_XB;         //
  7104.       AP.handle = dataID;                 // as explained above
  7105.       AP.recNo = recordToGet;             //
  7106.       AP.recPtr = &someRecord;
  7107.       rez = BULLET(&AP);
  7108.    }
  7109.    else
  7110.      printf("delete failed, err: %d\n",rez);
  7111. }
  7112.  
  7113. LP.func = UNLOCK_DATA_XB;
  7114. LP.handle = dataID;
  7115. LP.recStart = 0;                // unlock all
  7116. rez2 = BULLET(&LP);
  7117.  
  7118. if (rez==0) rez=rez2;
  7119. return(rez);
  7120.  
  7121.  
  7122. ΓòÉΓòÉΓòÉ 10.19. Memo Bypass (Memo Create, Open, Close, Read/Flush Header) ΓòÉΓòÉΓòÉ
  7123.  
  7124. #include "bullet2.h"
  7125.  
  7126. MEMODATAPACK MDP;               // packs used here
  7127.  
  7128.  
  7129. //  These five routines are normally performed automatically, as described
  7130. //  in the main documentation, and seldom would need to be called directly.
  7131.  
  7132.  
  7133. MDP.func = MEMO_BYPASS_XB;
  7134. MDP.dbfHandle = dataID;         // handle of DBF
  7135. MDP.memoBypass = BypassRoutineToDo;
  7136.  
  7137. // where BypassRoutineToDo is one of the following:
  7138. //
  7139. //   BYPASS_CREATE_MEMO
  7140. //   BYPASS_OPEN_MEMO
  7141. //   BYPASS_CLOSE_MEMO
  7142. //   BYPASS_READ_MEMO_HEADER
  7143. //   BYPASS_FLUSH_MEMO_HEADER
  7144.  
  7145. rez = BULLET(&MDP);
  7146. if (rez) return(rez);
  7147.  
  7148.  
  7149. ΓòÉΓòÉΓòÉ 10.20. Key Access Without Data Record Read ΓòÉΓòÉΓòÉ
  7150.  
  7151. #include "bullet2.h"
  7152.  
  7153. CHAR keyBuffer[64];             // enough for the largest possible key
  7154.  
  7155. ACCESSPACK AP;                  // packs used here
  7156.  
  7157. // -----------------------------------------------------------
  7158. // this section starts at the first in-order key and reads all
  7159. // keys in the index file in order
  7160.  
  7161. AP.func = FIRST_KEY_XB;
  7162. AP.handle = indexID;
  7163. AP.keyPtr = keyBuffer;
  7164. rez = BULLET(&AP);
  7165. while (rez==0) {
  7166.  
  7167.    // show first 8 bytes of key, and the record number the key is for
  7168.    printf("%8.8s  %9.9lu\r", keyBuffer, AP.recNo);
  7169.  
  7170.    AP.func = NEXT_KEY_XB;       // and get the next key...
  7171.    rez = BULLET(&AP);           // until all keys accessed
  7172. };
  7173. if (rez!=EXB_END_OF_FILE) return(rez); // expected rez is EXB_END_OF_FILE
  7174.  
  7175.  
  7176. // ----------------------------------------------------------
  7177. // this section starts at the last in-order key and reads all
  7178. // keys in the index file in reverse order
  7179.  
  7180. AP.func = LAST_KEY_XB;
  7181. AP.handle = indexID;
  7182. AP.keyPtr = keyBuffer;
  7183. rez = BULLET(&AP);
  7184. while (rez==0) {
  7185.  
  7186.    // show first 8 bytes of key, and the record number the key is for
  7187.    printf("%8.8s  %9.9lu\r", keyBuffer, AP.recNo);
  7188.  
  7189.    AP.func = PREV_KEY_XB;       // and get the previous key...
  7190.    rez = BULLET(&AP);           // until all keys accessed
  7191. };
  7192. if (rez!=EXB_TOP_OF_FILE) return(rez); // expected rez is EXB_TOP_OF_FILE
  7193.  
  7194. // this section starts at the first key that starts with "SM", or if
  7195. // no keys do, the first key after "SM", and gets that key
  7196. // keys in the index file in reverse order
  7197.  
  7198. memset(keyBuffer,0,64);         // ensure remaining bytes are \0 (required)
  7199. strcpy(keyBuffer,"SM");         // get key of "SM", if present (not likely)
  7200. AP.func = EQUAL_KEY_XB;
  7201. AP.handle = indexID;
  7202. AP.keyPtr = keyBuffer;
  7203. rez = BULLET(&AP);
  7204.  
  7205. // since "SM" is only being used as a partial key search criterion,
  7206. // it won't be found (though, of course, it is a valid key) in this
  7207. // example -- however, by using NEXT_KEY_XB, the next key is accessed,
  7208. // say, for example, "SMITH"...  It could also be "TIMBU" if there were
  7209. // no keys with values greater than "SM" and less than "TIMBU".
  7210.  
  7211. // Be aware that if another thread in this process (repeat:
  7212. // this process!) is accessing this index file (it's not likely that
  7213. // you will write your could so that this would happen), then you
  7214. // can no longer rely on any multi-call key access to be an atomic
  7215. // operation.  If you need to have more than one thread access the
  7216. // same index (and you require NEXT_KEY_XB or PREV_KEY_XB), then you
  7217. // must semaphore protect your code so you don't try to access the same
  7218. // index file.
  7219.  
  7220. if (rez!=EXB_KEY_NOT_FOUND) {   // expected
  7221.    AP.func = NEXT_KEY_XB;       // so get the first key after "SM"
  7222.    AP.handle = indexID;
  7223.    AP.keyPtr = keyBuffer;
  7224.    rez = BULLET(&AP);
  7225.    if (rez==0)
  7226.       printf("The first key >= SM is %s\n",AP.keyBuffer);
  7227. }
  7228.  
  7229.  
  7230. ΓòÉΓòÉΓòÉ 10.21. Building and Storing Raw Key ΓòÉΓòÉΓòÉ
  7231.  
  7232. #include "bullet2.h"
  7233.  
  7234. ACCESSPACK AP;                  // packs used here
  7235.  
  7236. // this example shows a simple database insert process
  7237. // INSERT_XB should be used instead since it does all this and then some
  7238. // files should be locked (not shown)
  7239.  
  7240. AP.func = ADD_RECORD_XB;
  7241. AP.handle = dataID;
  7242. AP.recPtr = &yourRecord;
  7243. rez = BULLET(&AP);
  7244. if (rez) return(rez);
  7245.  
  7246. // AP.recNo is returned by Bullet and will be used later
  7247.  
  7248. AP.func = BUILD_KEY_XB;
  7249. AP.handle = indexID;
  7250. AP.recPtr = &yourRecord;
  7251. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64];
  7252. rez = BULLET(&AP);
  7253. if (rez) return(rez);
  7254.  
  7255. // keyBuffer filled with key to store
  7256. // a \0\0 enumerator is attached if the index file was created with DUPS_ALLOWED
  7257.  
  7258. AP.func = STORE_KEY_XB;
  7259. AP.handle = indexID;
  7260. // AP.recNo is already set from the ADD_RECORD_XB call
  7261. AP.keyPtr = keyBuffer;
  7262. rez = BULLET(&AP);
  7263. if (rez) return(rez);
  7264.  
  7265. // if no error, the key was inserted in the index file and the record
  7266. // number was associated with that key -- next time you access that
  7267. // key, the record number is returned (along with the key itself) --
  7268. // and with that record number you access the data file
  7269.  
  7270. // when using this routine, you must check the error for a EXB_KEY_EXISTS
  7271. // error and if DUPS_ALLOWED, you must manage your own enumerator --
  7272. // INSERT_XB is the only routine that does this automatically so unless
  7273. // you have a real desire to manage this yourself (among other things)
  7274. // use INSERT_XB instead of all this.
  7275.  
  7276.  
  7277. ΓòÉΓòÉΓòÉ 10.22. Getting Current Key, Key for Rec/RecNo Pair, Deleting Key ΓòÉΓòÉΓòÉ
  7278.  
  7279. #include "bullet2.h"
  7280.  
  7281. ACCESSPACK AP;
  7282. LOCKPACK LP;                    // packs used here
  7283.  
  7284. AP.func = GET_CURRENT_KEY_XB;
  7285. AP.handle = indexID;
  7286. AP.keyPtr = keyBuffer;          // current key placed here by Bullet
  7287. rez = BULLET(&AP);
  7288. if (rez) return(rez);
  7289. printf("The last accessed key for indexID is in keyBuffer, including any enumerator\n");
  7290.  
  7291. // This next example assumes that you are maintaining your own method of
  7292. // transaction rollback, and are about to delete the last item added to the
  7293. // database: in this case, the last data record is removed from the one
  7294. // DBF data file, and the key for that record is removed from the index file
  7295. // -- normally, you wouldn't do this, but if you have the need...
  7296.  
  7297. rez = InsertToDatabaseHoweverYouDoIt(yourPtr);
  7298.  
  7299. // Assume the above called succeeded, but you've decided, for whatever reason,
  7300. // that you want to backout the insert... normally, if you used INSERT_XB to
  7301. // insert a record/key into a database, you'd already have the record number
  7302. // used AND the key used for the record (for each if more than one) -- but for
  7303. // this example, assume that only the record number is known.  Steps done
  7304. // to remove the record and key for this would be:
  7305. //
  7306. //  1. Exclusive full-lock files
  7307. //  2. Get the record data at the record number (GET_RECORD_XB)
  7308. //  3. Get the key for this record/recNo pair (GET_KEY_FOR_RECORD_XB)
  7309. //  4. Delete the key (DELETE_KEY_XB) (delete the key before deleting the record)
  7310. //  5. Delete the record data (DEBUMP_RECORD_XB) (record must be last record in file)
  7311. //  6. Unlock files
  7312.  
  7313. // lock files being processed
  7314.  
  7315. LP.func = LOCK_XB;
  7316. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7317. LP.xlMode = LOCK_EXCLUSIVE;     // exclusive lock for index
  7318. LP.dlMode = LOCK_EXCLUSIVE;     // exclusive lock for data
  7319. LP.nextPtr = NULL;              // only one pack
  7320. rez = BULLET(&LP);
  7321. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7322.  
  7323. // get actual data record for record number
  7324.  
  7325. AP.func = GET_RECORD_XB;
  7326. AP.handle = dataID;
  7327. AP.recNo = recNoToDelete;       // get this record to...
  7328. AP.recPtr = &yourRecord;        // ...this data record buffer (a structure var)
  7329. rez = BULLET(&AP);
  7330. if (rez) goto MustAlwaysUnlock;
  7331.  
  7332. // now have the data record/data number pair --
  7333. // it must be the last physical record in the data file -- if this cannot
  7334. // be known, use STAT_DATA_XB to verify that recNoToDelete==SDP.records
  7335.  
  7336. AP.func = GET_KEY_FOR_RECORD_XB;
  7337. AP.handle = indexID;
  7338. AP.recNo = recNoToDelete;
  7339. AP.recPtr = &yourRecord;
  7340. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64]; key returned here
  7341. rez = BULLET(&AP);
  7342. if (rez) goto MustAlwaysUnlock;
  7343.  
  7344. // now have the key (with any attached enumerator) in keyBuffer, delete it
  7345.  
  7346. AP.func = DELETE_KEY_XB;
  7347. AP.handle = indexID;
  7348. AP.keyPtr = keyBuffer;          // was set with key by GET_KEY_FOR_RECORD_XB
  7349. rez = BULLET(&AP);
  7350. if (rez) goto MustAlwaysUnlock;
  7351.  
  7352. // and delete (physically remove) the data record
  7353.  
  7354. AP.func = DEBUMP_RECORD_XB;
  7355. AP.handle = dataID;
  7356. AP.recNo = recNoToDelete;
  7357. rez = BULLET(&AP);
  7358. // if (rez) goto MustAlwaysUnlock;
  7359.  
  7360. MustAlwaysUnlock:   // unlock ALWAYS required if lock succeeded
  7361.  
  7362. LP.func = UNLOCK_XB;
  7363. LP.handle = indexID;
  7364. LP.nextPtr = NULL;
  7365. rez2 = BULLET(&LP);
  7366. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  7367.  
  7368. if (rez==0) rez=rez2;
  7369. return(rez);
  7370.  
  7371.  
  7372. ΓòÉΓòÉΓòÉ 10.23. Get Data by Key Order ΓòÉΓòÉΓòÉ
  7373.  
  7374. #include "bullet2.h"
  7375.  
  7376. ACCESSPACK AP;                  // packs used here
  7377.  
  7378. // First example starts at first in-order data and moves through to last
  7379.  
  7380. AP.func = GET_FIRST_XB;
  7381. AP.handle = indexID;
  7382. AP.recPtr = &yourRecord;        // struct yourStructure yourRecord;
  7383. AP.keyPtr = keyBuffer;          // CHAR keyBuffer[64];
  7384. rez = BULLET(&AP);
  7385. if (rez) return(rez);
  7386. printf("The first in-order key is in keyBuffer and its record in yourRecord\n");
  7387.  
  7388. AP.func = GET_NEXT_XB;          // other parm same as set above
  7389. while (rez==0) {
  7390.    rez = BULLET(&AP);
  7391.    if (rez) break;
  7392.    printf("The next in-order key is in keyBuffer and its record in yourRecord\n");
  7393. }
  7394. if (rez==EXB_END_OF_FILE) rez==0; // expected rez after end of file
  7395. if (rez) return(rez);
  7396.  
  7397.  
  7398. // Second example starts at last in-order data and moves through to first
  7399. // note: since above already is past last, the call to GET_LAST_XB in
  7400. //       this example would not be necessary -- a call to GET_PREV_XB
  7401. //       could have been made directly -- however, it doesn't matter
  7402.  
  7403. AP.func = GET_LAST_XB;
  7404. AP.handle = indexID;
  7405. AP.recPtr = &yourRecord;
  7406. AP.keyPtr = keyBuffer;
  7407. rez = BULLET(&AP);
  7408. if (rez) return(rez);
  7409. printf("The last in-order key is in keyBuffer and its record in yourRecord\n");
  7410.  
  7411. AP.func = GET_PREV_XB;          // other parms same as set above
  7412. while (rez==0) {
  7413.    rez = BULLET(&AP);
  7414.    if (rez) break;
  7415.    printf("The previous in-order key is in keyBuffer and its record in yourRecord\n");
  7416. }
  7417. if (rez==EXB_TOP_OF_FILE) rez==0; // expected rez before at beginning of file
  7418. if (rez) return(rez);
  7419.  
  7420.  
  7421. // Third example performs a GET_EQUAL_OR_GREATER operation, typically
  7422. // used to locate to a key based on a partial search criterion
  7423.  
  7424. AP.func = GET_EQUAL_XB;
  7425. AP.handle = indexID;
  7426. AP.recPtr = &yourRecord;    // to be filled on return, if found
  7427.  
  7428. memset(keyBuffer,0,sizeof(keyBuffer);   // clear it out (required)
  7429. strcpy(keyBuffer,"KING");               // find first key starting with 'KING'
  7430. AP.keyPtr = keyBuffer;
  7431.  
  7432. rez = BULLET(&AP);
  7433. if (rez==0)
  7434.    printf("Matched search key in keyBuffer EXACTLY -- its record is in yourRecord\n");
  7435. else if (rez==EXB_KEY_NOT_FOUND) {
  7436.  
  7437.    // since not found, get the following in-order one (say, 'KINGSTON')
  7438.  
  7439.    AP.func = GET_NEXT_XB;
  7440.    rez = BULLET(&AP);
  7441.    if (rez) return(rez);
  7442.  
  7443.    printf("Not exact, but next greater key is in keyBuffer and its record is in yourRecord\n");
  7444. }
  7445. else
  7446.    return(rez);
  7447.  
  7448.  
  7449. ΓòÉΓòÉΓòÉ 10.24. Insert Data Record with Key Into Database ΓòÉΓòÉΓòÉ
  7450.  
  7451. #include "bullet2.h"
  7452.  
  7453. ACCESSPACK AP;
  7454. LOCKPACK LP;                    // packs used here
  7455.  
  7456. LP.func = LOCK_XB;
  7457. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7458. LP.xlMode = LOCK_EXCLUSIVE;     // exclusive lock for index
  7459. LP.dlMode = LOCK_EXCLUSIVE;     // exclusive lock for data
  7460. LP.nextPtr = NULL;              // only one pack
  7461. rez = BULLET(&LP);
  7462. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7463.  
  7464. AP.func = INSERT_XB;
  7465. AP.handle = indexID;
  7466. AP.recNo = 0;                   // must be zero
  7467. AP.recPtr = &yourRecord;        // contains data record
  7468. AP.keyPtr = keyBuffer;          // empty, on return has key stored
  7469. AP.nextPtr = NULL;              // only the single pack
  7470. rez = BULLET(&AP);
  7471.  
  7472. // on return, as on all transaction-list routines, rez is not the return
  7473. // code but is the pack item that failed (neg if data, pos if index)
  7474.  
  7475. if (rez==0)
  7476.    printf("okay\n");
  7477. else if (rez < 0)
  7478.    printf("insert failed with data, err: %d\n",LP.stat);
  7479. else
  7480.    printf("insert failed with index, err: %d\n",LP.stat);
  7481.  
  7482.  
  7483. // if locked, MUST unlock!
  7484.  
  7485. LP.func = UNLOCK_XB;
  7486. LP.handle = indexID;
  7487. LP.nextPtr = NULL;
  7488. rez2 = BULLET(&LP);
  7489. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  7490. if (rez==0) rez=rez2    // return the most interesting error, if any
  7491.  
  7492.  
  7493. ΓòÉΓòÉΓòÉ 10.25. Update Data Record with Key Update ΓòÉΓòÉΓòÉ
  7494.  
  7495. #include "bullet2.h"
  7496.  
  7497. ACCESSPACK AP;
  7498. LOCKPACK LP;                    // packs used here
  7499.  
  7500. LP.func = LOCK_XB;
  7501. LP.handle = indexID;            // also locks indexID's owner (its DBF)
  7502. LP.xlMode = LOCK_SHARED;        // shared lock for index
  7503. LP.dlMode = LOCK_SHARED;        // shared lock for data
  7504. LP.nextPtr = NULL;              // only one pack
  7505. rez = BULLET(&LP);
  7506. if (rez) return(LP.stat);       // rez for transaction-list is NOT the error
  7507.  
  7508. AP.func = GET_FIRST_XB;         // get first key's data record (and its recNo)
  7509. AP.handle = indexID;
  7510. AP.recPtr = &yourRecord;
  7511. AP.keyPtr = keyBuffer;
  7512. rez = BULLET(&AP);
  7513. if (rez==0) {
  7514.  
  7515.    // assume that we want to change this entry now (as if we weren't sure
  7516.    // that we wanted to initially, hence the initial shared lock) --
  7517.    // this requires write access so relock to allow write access
  7518.  
  7519.    LP.func = RELOCK_XB;
  7520.    LP.handle = indexID;
  7521.    LP.xlMode = LOCK_EXCLUSIVE;  // exclusive lock for index
  7522.    LP.dlMode = LOCK_EXCLUSIVE;  // exclusive lock for data
  7523.    LP.nextPtr = NULL;
  7524.    rez = BULLET(&LP);
  7525.    if (rez) rez=LP.stat         // xaction-list routine so use LP.stat
  7526.    if (rez==0) {
  7527.  
  7528.       strcpy(yourRecord.someField,"new field data");
  7529.  
  7530.       // AP.recNo has been set by Bullet GET_XB call above
  7531.  
  7532.       AP.func = UPDATE_XB;
  7533.       AP.nextPtr = NULL;        // all other AP members set above
  7534.       rez = BULLET(&AP);
  7535.  
  7536.       // on return, as on all transaction-list routines, rez is not the return
  7537.       // code but is the pack item that failed (neg if data, pos if index)
  7538.  
  7539.       if (rez==0)
  7540.          printf("okay\n");
  7541.       else if (rez < 0)
  7542.          printf("update failed with data, err: %d\n",LP.stat);
  7543.       else
  7544.          printf("update failed with index, err: %d\n",LP.stat);
  7545.    }
  7546.    else
  7547.       printf("relock failed, rez: %d  err: %d\n",rez,LP.stat);
  7548. }
  7549.  
  7550. // if locked, MUST unlock!
  7551.  
  7552. LP.func = UNLOCK_XB;
  7553. LP.handle = indexID;
  7554. LP.nextPtr = NULL;
  7555. rez2 = BULLET(&LP);
  7556. if (rez2) rez2=LP.stat; // rez for transaction-list is NOT the error
  7557. if (rez==0) rez=rez2    // return the most interesting error, if any
  7558.  
  7559.  
  7560. ΓòÉΓòÉΓòÉ 10.26. Remote Drive, File/Device Check ΓòÉΓòÉΓòÉ
  7561.  
  7562. #include "bullet2.h"
  7563.  
  7564. REMOTEPACK RP;                  // packs used here
  7565.  
  7566. // check if file in handle (or device handle) is on a 'network' drive
  7567.  
  7568. RP.func = CHECK_REMOTE_XB;
  7569. RP.handle = indexID;            // check if indexID handle is on a network
  7570. rez = BULLET(&RP);
  7571. if (rez) return(rez);
  7572. if (RP.isRemote)
  7573.    printf("handle is on a network drive\n");
  7574.  
  7575. // check if drive is a 'network' drive
  7576.  
  7577. RP.func = CHECK_REMOTE_XB;
  7578. RP.handle = 0;                  // set RP.handle to 0 to check drive
  7579. RP.drive = 0;                   // check if current drive is network drive
  7580. rez = BULLET(&RP);              // to check drive C:, set RP.drive=3
  7581. if (rez) return(rez);           // D: is RP.drive=4, and so on
  7582. if (RP.isRemote)
  7583.    printf("current drive is a network drive\n");
  7584.  
  7585.  
  7586. ΓòÉΓòÉΓòÉ 10.27. Relock Individual File ΓòÉΓòÉΓòÉ
  7587.  
  7588. #include "bullet2.h"
  7589.  
  7590. LOCKPACK LP;
  7591. STATHANDLEPACK SHP;
  7592. STATDATAPACK SDP;
  7593. STATINDEXPACK SIP;              // packs used here
  7594.  
  7595. // given a handle, determine if it's DBF or index
  7596. // check if currently locked
  7597. // if locked, determine if shared or exclusive lock
  7598. // if exclusive lock, relock to shared
  7599. // if not locked, do nothing
  7600.  
  7601. SHP.func = STAT_HANDLE_XB;
  7602. SHP.handle = passedHandle;
  7603. rez = BULLET(&SHP);
  7604. if (SHP.ID==-1)
  7605.    puts("Handle is not a Bullet data or index file\n");
  7606. else {
  7607.    if (SHP.ID==0) {
  7608.  
  7609.       // normally, you lock before calling this routine but since
  7610.       // SIP.lockCount and SIP.flags are all that is being checked,
  7611.       // and since nothing is to be done if the handle is not locked,
  7612.       // it's okay in this instance to use this routine without
  7613.       // first explicitly locking the handle
  7614.  
  7615.       SIP.func = STAT_INDEX_XB;
  7616.       SIP.handle = passedHandle;
  7617.       rez = BULLET(&SIP);
  7618.       if (rez) goto ErrorHandler;
  7619.  
  7620.       // if locked, check if the lock is exclusive
  7621.  
  7622.       if (SIP.lockCount) {              // count of active full locks
  7623.  
  7624.          if ((SIP.flags & 4)==0) {      // bit2=0 means lock is not shared
  7625.  
  7626.             // currently exclusive, make it shared
  7627.  
  7628.             LP.func = RELOCK_INDEX_XB;
  7629.             LP.handle = passedHandle;
  7630.             LP.xlMode = LOCK_SHARED;
  7631.             rez = BULLET(&LP);
  7632.             if (rez) goto ErrorHandler;
  7633.          }
  7634.       }
  7635.    }
  7636.    else {
  7637.  
  7638.       SDP.func = STAT_DATA_XB;
  7639.       SDP.handle = passedHandle;
  7640.       rez = BULLET(&SDP);
  7641.       if (rez) goto ErrorHandler;
  7642.  
  7643.       if (SDP.lockCount) {              // count of active full locks
  7644.  
  7645.          if ((SDP.flags & 4)==0) {      // bit2=0 means lock is not shared
  7646.  
  7647.             // currently exclusive, make it shared
  7648.  
  7649.             LP.func = RELOCK_DATA_XB;
  7650.             LP.handle = passedHandle;
  7651.             LP.dlMode = LOCK_SHARED;
  7652.             LP.startRec = 0;            // entire file
  7653.             rez = BULLET(&LP);
  7654.             if (rez) goto ErrorHandler;
  7655.          }
  7656.       }
  7657.    }
  7658. }
  7659.  
  7660.  
  7661. ΓòÉΓòÉΓòÉ 10.28. DOS Disk Routines Through Bullet ΓòÉΓòÉΓòÉ
  7662.  
  7663. #include "bullet2.h"
  7664.  
  7665. DOSFILEPACK DFP;                // packs used here
  7666.  
  7667. CHAR dataDirname[] = "under";
  7668. CHAR dataFilename[]= "under\\data.dbf";
  7669. CHAR newFilename[] = "under\\newdata.dbf";
  7670.  
  7671. // check if pathame can be access for read/write denynone (expected not here)
  7672.  
  7673. DFP.func = ACCESS_FILE_DOS;
  7674. DFP.filenamePtr = dataFilename;
  7675. DFP.asMode = 0x42;
  7676. rez = BULLET(&DFP);
  7677. if (rez==0) return(0);          // file already exists
  7678. if (rez==5) return(5);          // access denied (exists but in use)
  7679. // other errors possible, too, do the Make and Create and go by those results
  7680.  
  7681. // make directory for file
  7682.  
  7683. DFP.func = MAKE_DIR_DOS;
  7684. DFP.filenamePtr = dataDirname;
  7685. rez = BULLET(&DFP);
  7686. if (rez) rez=0;                 // can't create subdirectory (already exists?)
  7687.  
  7688. // create file
  7689.  
  7690. DFP.func = CREATE_FILE_DOS;
  7691. DFP.filenamePtr = dataFilename;
  7692. DFP.attr = 0;                   // 'normal' attributes
  7693. rez = BULLET(&DFP);
  7694. if (rez) return(rez);           // can't create file
  7695.  
  7696. // open file
  7697.  
  7698. DFP.func = OPEN_FILE_DOS;
  7699. DFP.filenamePtr = dataFilename;
  7700. DFP.asMode = 0x42;
  7701. rez = BULLET(&DFP);
  7702. if (rez) return(rez);           // can't open file
  7703.  
  7704. // DFP.handle is set by OPEN_FILE_DOS call above
  7705. // pre-allocate file space
  7706.  
  7707. DFP.func = EXPAND_FILE_DOS;
  7708. // DFP.handle already set
  7709. // DFP.asMode already set
  7710. DFP.bytes = 128*1024;           // set filesize to 128KB
  7711. rez = BULLET(&DFP);
  7712. if (rez) return(rez);           // can't do it (close file before return)
  7713.  
  7714. CHAR writeStuff[]="Write this string to offset 888";
  7715.  
  7716. DFP.func = SEEK_FILE_DOS;
  7717. // DFP.handle already set
  7718. DFP.seekTo = 888;
  7719. DFP.method = 0;                 // from start of file
  7720. rez = BULLET(&DFP);
  7721. if (rez) return(rez);           // can't do it (close...)
  7722.  
  7723. // write the string to disk
  7724.  
  7725. DFP.func = WRITE_FILE_DOS;
  7726. // DFP.handle already set
  7727. DFP.bytes = strlen(writeStuff);
  7728. DFP.bufferPtr = writeStuff;
  7729. rez = BULLET(&DFP);
  7730. if (rez) return(rez);
  7731.  
  7732. // commit to the deep
  7733.  
  7734. DFP.func = COMMIT_FILE_DOS;
  7735. // DFP.handle already set
  7736. rez = BULLET(&DFP);
  7737. if (rez) return(rez);
  7738.  
  7739. // reposition to where write started so can read what was written
  7740.  
  7741. DFP.func = SEEK_FILE_DOS;
  7742. // DFP.handle already set
  7743. DFP.seekTo = 888;
  7744. DFP.method = 0;
  7745. rez = BULLET(&DFP);
  7746. if (rez) return(rez);
  7747.  
  7748. CHAR readBuffer[128];
  7749.  
  7750. DFP.func = READ_FILE_DOS;
  7751. // DFP.handle already set
  7752. DFP.bytes = strlen(writeStuff); // read it back
  7753. DFP.bufferPtr = readBuffer;
  7754. rez = BULLET(&DFP);
  7755. if (rez) return(rez);
  7756. if (DFP.bytes != strlen(writeStuff))
  7757.    printf("read came up short!\n");
  7758.  
  7759. DFP.func = CLOSE_FILE_DOS;
  7760. // DFP.handle already set
  7761. rez = BULLET(&DFP);
  7762. if (rez) return(rez);
  7763. DFP.handle = 0;                 // it's gone (closed, anyway)
  7764.  
  7765. // rename the file
  7766.  
  7767. DFP.func = RENAME_FILE_DOS;
  7768. DFP.filenamePtr = dataFilename;
  7769. DFP.newFilenamePtr = newFilename;
  7770. rez = BULLET(&DFP);
  7771. if (rez) return(rez);
  7772.  
  7773. // and get rid of it (known now as newFilename)
  7774.  
  7775. DFP.func = DELETE_FILE_DOS;
  7776. DFP.filenamePtr = newFilename;
  7777. rez = BULLET(&DFP);
  7778. return(rez);
  7779.  
  7780. // Why the DosXXX routines when they're standard API?  Not all
  7781. // language tools are able to directly call the API, but can
  7782. // call them indirectly through the Bullet DLL.
  7783.  
  7784.  
  7785. ΓòÉΓòÉΓòÉ 11. Bullet Errors ΓòÉΓòÉΓòÉ
  7786.  
  7787. Bullet error codes are numbered so that they do not overlap OS error codes. 
  7788. The first general Bullet error number is 8193, but Bullet also returns select 
  7789. system error code numbers instead of duplicating system codes (those listed 
  7790. below less than 8192).  In addition, if the error is reported by the OS (for 
  7791. example, attempting to access a locked file), then the OS error in returned by 
  7792. Bullet.  For a list of OS errors, see OS/2 Dos API Errors. 
  7793.  
  7794. System Error Codes
  7795.  
  7796.    8    EXB_NOT_ENOUGH_MEMORY
  7797.         cannot get memory requested
  7798.  
  7799.   38    EXB_UNEXPECTED_EOF
  7800.         unexpected end-of-file where bytes requested for read exceeded EOF
  7801.  
  7802.   39    EXB_DISK_FULL
  7803.         disk full on WriteFile
  7804.  
  7805.   80    EXB_FILE_EXISTS
  7806.         cannot create file since it already exists
  7807.  
  7808.  
  7809. 8192+   EXB_OR_WITH_FAULTS
  7810.         1=flush failed on handle close
  7811.         2=free memory failed on handle close
  7812.         4=failed memo handle close (data handle only)
  7813.  
  7814.         During a CLOSE_XB routine, the close process continues
  7815.         regardless of errors, and so the errors are accumulated.
  7816.         For example, 8193 means the flush failed, and 8195 means
  7817.         both the flush and the free failed (8192+1+2=8195).
  7818.         If the error occurred in the actual DosClose() API call,
  7819.         only that error is returned (it will be an OS error code).
  7820.  
  7821.  
  7822. 8300    EXB_ILLEGAL_CMD
  7823.         function not allowed
  7824.  
  7825. 8301    EXB_OLD_DOS
  7826.         OS version < MIN_DOS_NEEDED
  7827.  
  7828. 8302    EXB_NOT_INITIALIZED
  7829.         init not active, must do INIT_XB before using Bullet
  7830.  
  7831. 8303    EXB_ALREADY_INITIALIZED
  7832.         init already active, must do EXIT_XB first
  7833.  
  7834. 8304    EXB_TOO_MANY_HANDLES
  7835.         more than 1024 opens requested,
  7836.         or more than license permits (100, 250, 1024)
  7837.  
  7838. 8305    EXB_SYSTEM_HANDLE
  7839.         Bullet won't use or close handles 0-2
  7840.  
  7841. 8306    EXB_FILE_NOT_OPEN
  7842.         the handle is not a Bullet handle, including the
  7843.         handle supplied in OP.xbLink
  7844.  
  7845. 8307    EXB_FILE_IS_DIRTY
  7846.         tried to reload header but current still dirty;
  7847.         flush the file before reloading the header
  7848.  
  7849. 8308    EXB_BAD_FILETYPE
  7850.         attempted to do a key file operation on non-key file,
  7851.         or a data operation on a non-data file
  7852.  
  7853. 8309    EXB_TOO_MANY_PACKS
  7854.         too many INSERT, UPDATE, REINDEX, LOCK_XB packs (more than 256)
  7855.  
  7856. 8310    EXB_NULL_RECPTR
  7857.         null record pointer passed to Bullet (.recPtr==NULL)
  7858.  
  7859. 8311    EXB_NULL_KEYPTR
  7860.         null key pointer passed to Bullet (.keyPtr==NULL)
  7861.  
  7862. 8312    EXB_NULL_MEMOPTR
  7863.         null memo pointer passed to Bullet (.memoPtr==NULL)
  7864.  
  7865. 8313    EXB_EXPIRED
  7866.         evaluation time period has expired, reinstall if time remaining
  7867.  
  7868. 8314    EXB_BAD_INDEX
  7869.         Query/SetSysVars index selection is beyond the last one
  7870.  
  7871. 8315    EXB_RO_INDEX
  7872.         SetSysVars index item is read-only
  7873.  
  7874. 8316    EXB_FILE_BOUNDS
  7875.         file size > 4GB, or greater than the SetSysVars value
  7876.  
  7877.  
  7878. Multi-access Error Codes
  7879.  
  7880. 8401    EXB_BAD_LOCK_MODE
  7881.         lock mode (LP) not valid, must be 0 or 1
  7882.  
  7883. 8402    EXB_NOTHING_TO_RELOCK
  7884.         cannot relock without existing full-lock
  7885.  
  7886. 8403    ERR_SHARED_LOCK_ON
  7887.         unlikely error, write access needed for flush, but lock is shared
  7888.  
  7889.  
  7890. Index Error Codes
  7891.  
  7892. 8501    EXB_KEY_NOT_FOUND
  7893.         exact match of key not found
  7894.  
  7895. 8502    EXB_KEY_EXISTS
  7896.         key exists already and dups not allowed
  7897.  
  7898. 8503    EXB_END_OF_FILE
  7899.         already at last index order
  7900.  
  7901. 8504    EXB_TOP_OF_FILE
  7902.         already at first index order
  7903.  
  7904. 8505    EXB_EMPTY_FILE
  7905.         nothing to do since no keys
  7906.  
  7907. 8506    EXB_CANNOT_GET_LAST
  7908.         cannot locate last key
  7909.  
  7910. 8507    EXB_BAD_INDEX_STACK
  7911.         index file is corrupt
  7912.  
  7913. 8508    EXB_BAD_INDEX_READ0
  7914.         index file is corrupt
  7915.  
  7916. 8509    EXB_BAD_INDEX_WRITE0
  7917.         index file is corrupt
  7918.  
  7919.  
  7920. 8521    EXB_OLD_INDEX
  7921.         incompatible Bullet index, use ReindexOld subroutine, if available
  7922.  
  7923. 8522    EXB_UNKNOWN_INDEX
  7924.         not a Bullet index file
  7925.  
  7926. 8523    EXB_KEY_TOO_LONG
  7927.         keylength > 62 (or 64 if unique), or is 0
  7928.  
  7929.  
  7930. 8531    EXB_PARSER_NULL
  7931.         parser function pointer is NULL
  7932.  
  7933. 8532    EXB_BUILDER_NULL
  7934.         build key function pointer is NULL
  7935.  
  7936. 8533    EXB_BAD_SORT_FUNC
  7937.         CIP.sortFunction not valid (not 1-6, or a custom sort-compare)
  7938.  
  7939. 8534    EXB_BAD_NODE_SIZE
  7940.         CIP.nodeSize is not 512, 1024, or 2048
  7941.  
  7942. 8535    EXB_FILENAME_TOO_LONG
  7943.         CIP.filenamePtr->pathname greater than file system allows
  7944.  
  7945.         This error is detected only for the file system installed,
  7946.         and does not detect using pathnames greater than 80 on a FAT
  7947.         system if HPFS is installed.  The OS returns its own error
  7948.         in this case, after the fact.
  7949.  
  7950.  
  7951. 8541    EXB_KEYX_NULL
  7952.         key expression is effectively NULL
  7953.  
  7954. 8542    EXB_KEYX_TOO_LONG
  7955.         CIP.keyExpPtr->expression is greater than 159 bytes
  7956.  
  7957. 8543    EXB_KEYX_SYM_TOO_LONG
  7958.         fieldname/funcname in expression is longer than 10 chars
  7959.  
  7960. 8544    EXB_KEYX_SYM_UNKNOWN
  7961.         fieldname/funcname in expression is unknown or misspelled
  7962.  
  7963. 8545    EXB_KEYX_TOO_MANY_SYMS
  7964.         too many symbols/fields used in expression (16 max)
  7965.  
  7966. 8546    EXB_KEYX_BAD_SUBSTR
  7967.         invalid SUBSTR() operand in expression
  7968.  
  7969. 8547    EXB_KEYX_BAD_SUBSTR_SZ
  7970.         SUBSTR() exceeds field's size
  7971.  
  7972. 8548    EXB_KEYX_BAD_FORM
  7973.         didn't match expected symbol in expression (missing paren, etc.)
  7974.  
  7975.  
  7976. 8551    EXB_NO_READS_FOR_RUN
  7977.         unlikely error, use different reindex buffer size to fix
  7978.  
  7979. 8552    EXB_TOO_MANY_RUNS
  7980.         unlikely error, too many runs (64K or more runs)
  7981.  
  7982. 8553    EXB_TOO_MANY_RUNS_FOR_BUFFER
  7983.         unlikely error, too many runs for run buffer
  7984.  
  7985. 8554    EXB_TOO_MANY_DUPLICATES
  7986.         more than 64K "identical" keys since the last enumerator used
  7987.         was 0xFFFF -- if ever you have this error, REINDEX_XB should
  7988.         be used to resequence the enumerators
  7989.  
  7990.  
  7991. 8561    EXB_INSERT_RECNO_BAD
  7992.         AP.recNo cannot be > 0 if inserting with INSERT_XB
  7993.  
  7994. 8562    EXB_PREV_APPEND_EMPTY
  7995.         no previous append for INSERT_XB yet AP.recNo==0x80000000
  7996.  
  7997. 8563    EXB_PREV_APPEND_MISMATCH
  7998.         previous append's xbLink does not match this
  7999.         -- if this pack's AP.recNo=0x80000000 then this pack's AP.handle
  8000.         must be the same handle as that of the last pack that added a record
  8001.  
  8002. 8564    EXB_INSERT_KBO_FAILED
  8003.         could not back out key at INSERT_XB
  8004.  
  8005. 8565    EXB_INSERT_DBO_FAILED
  8006.         could not back out data records at INSERT_XB
  8007.  
  8008.  
  8009. 8571    WRN_NOTHING_TO_UPDATE
  8010.         all AP.recNo=0 at UPDATE_XB so nothing to do
  8011.  
  8012. 8572    EXB_INTERNAL_UPDATE
  8013.         internal error UPDATE_XB, not in handle/record# list
  8014.  
  8015. 8573    EXB_FAILED_DATA_RESTORE
  8016.         could not restore original data record (*)
  8017.  
  8018. 8574    EXB_FAILED_KEY_DELETE
  8019.         could not remove new key (*)
  8020.  
  8021. 8575    EXB_FAILED_KEY_RESTORE
  8022.         could not restore original key(*)
  8023.  
  8024.         (*) original error, which forced a back-out, has been
  8025.         replaced by this error -- this error is always returned
  8026.         in the first AP.stat (-1 on data, 1 on index)
  8027.  
  8028.  
  8029. Data Error Codes
  8030.  
  8031. 8601    EXB_EXT_XBLINK
  8032.         xbLink handle is not an internal DBF, as was specified during the
  8033.         index file's creation -- the Bullet routine called requires a Bullet
  8034.         DBF data file (instead use index-only access methods like NEXT_KEY_XB).
  8035.  
  8036. 8602    EXB_FIELDNAME_TOO_LONG
  8037.         fieldname is > 10 characters
  8038.  
  8039. 8603    EXB_RECORD_TOO_LONG
  8040.         record length is > 64K
  8041.  
  8042. 8604    EXB_FIELD_NOT_FOUND
  8043.         fieldname not found in descriptor info
  8044.  
  8045. 8605    EXB_BAD_FIELD_COUNT
  8046.         fields <= 0 or >= MAX_FIELDS; also use of a field number which
  8047.         is beyond the last field
  8048.  
  8049. 8606    EXB_BAD_HEADER
  8050.         bad header (reclen=0, etc.)
  8051.  
  8052. 8607    EXB_BUFFER_TOO_SMALL
  8053.         buffer too small (pack buffer < record length)
  8054.  
  8055. 8608    EXB_INTERNAL_PACK
  8056.         internal error in PackRecords
  8057.  
  8058. 8609    EXB_BAD_RECNO
  8059.         record number=0 or > records in data file header, or
  8060.         pack attempt on empty data file
  8061.  
  8062. 8610    WRN_RECORD_TAGGED
  8063.         record's tag field matches skip tag
  8064.  
  8065.  
  8066. Memo Error Codes
  8067.  
  8068. 8701    WRN_CANNOT_OPEN_MEMO
  8069.         the DBF header has bits 3 & 7 set, which indicates that a memo
  8070.         file is attached to this DBF, but the DBT memo file failed to open
  8071.         -- the DBF open continues, with this warning code returned
  8072.  
  8073. 8702    EXB_MEMO_NOT_OPEN
  8074.         no open memo file for operation
  8075.  
  8076. 8703    EXB_BAD_BLOCKSIZE
  8077.         memo blocksize must be at least 24 bytes
  8078.  
  8079. 8704    EXB_MEMO_DELETED
  8080.         memo is deleted
  8081.  
  8082. 8705    EXB_MEMO_PAST_END
  8083.         memo data requested is past end of record
  8084.  
  8085. 8706    EXB_BAD_MEMONO
  8086.         memo number is not valid
  8087.  
  8088. 8707    EXB_MEMO_IN_USE
  8089.         memo add encountered likely corrupt memo file
  8090.         -- avail list indicates this memo record is deleted, but the memoAvail
  8091.         link for the memo indicates it is use (memoAvail link==0x8FFFF)
  8092.  
  8093. 8708    EXB_BAD_AVAIL_LINK
  8094.         memo avail link cannot be valid (e.g., memoAvail==0)
  8095.  
  8096. 8709    EXB_MEMO_ZERO_SIZE
  8097.         memo data has no size (size is 0)
  8098.  
  8099. 8710    EXB_MEMO_IS_SMALLER
  8100.         memo attempt to shrink but memo size is already <= size requested
  8101.  
  8102.  
  8103. ΓòÉΓòÉΓòÉ 12. OS/2 Dos API Errors ΓòÉΓòÉΓòÉ
  8104.  
  8105.  
  8106.   0   NO_ERROR
  8107.           No error occurred.
  8108.  
  8109.   1   ERROR_INVALID_FUNCTION
  8110.           Invalid function number.
  8111.  
  8112.   2   ERROR_FILE_NOT_FOUND
  8113.           File not found.
  8114.  
  8115.   3   ERROR_PATH_NOT_FOUND
  8116.           Path not found.
  8117.  
  8118.   4   ERROR_TOO_MANY_OPEN_FILES
  8119.           Too many open files (no handles left).
  8120.  
  8121.   5   ERROR_ACCESS_DENIED
  8122.           Access denied.
  8123.  
  8124.   6   ERROR_INVALID_HANDLE
  8125.           Invalid handle.
  8126.  
  8127.   7   ERROR_ARENA_TRASHED
  8128.           Memory control blocks destroyed.
  8129.  
  8130.   8   ERROR_NOT_ENOUGH_MEMORY
  8131.           Insufficient memory.
  8132.  
  8133.   9   ERROR_INVALID_BLOCK
  8134.           Invalid memory-block address.
  8135.  
  8136.   10   ERROR_BAD_ENVIRONMENT
  8137.           Invalid environment.
  8138.  
  8139.   11   ERROR_BAD_FORMAT
  8140.           Invalid format.
  8141.  
  8142.   12   ERROR_INVALID_ACCESS
  8143.           Invalid access code.
  8144.  
  8145.   13   ERROR_INVALID_DATA
  8146.           Invalid data.
  8147.  
  8148.   14   Reserved.
  8149.  
  8150.  
  8151.   15   ERROR_INVALID_DRIVE
  8152.           Invalid drive specified.
  8153.  
  8154.   16   ERROR_CURRENT_DIRECTORY
  8155.           Attempting to remove current directory.
  8156.  
  8157.   17   ERROR_NOT_SAME_DEVICE
  8158.           Not same device.
  8159.  
  8160.   18   ERROR_NO_MORE_FILES
  8161.           No more files.
  8162.  
  8163.   19   ERROR_WRITE_PROTECT
  8164.           Attempt to write on write-protected diskette.
  8165.  
  8166.   20   ERROR_BAD_UNIT
  8167.           Unknown unit.
  8168.  
  8169.   21   ERROR_NOT_READY
  8170.           Drive not ready.
  8171.  
  8172.   22   ERROR_BAD_COMMAND
  8173.           Unknown command.
  8174.  
  8175.   23   ERROR_CRC
  8176.           Data error - cyclic redundancy check.
  8177.  
  8178.   24   ERROR_BAD_LENGTH
  8179.           Invalid request structure length.
  8180.  
  8181.   25   ERROR_SEEK
  8182.           Seek error.
  8183.  
  8184.   26   ERROR_NOT_DOS_DISK
  8185.           Unknown media type.
  8186.  
  8187.   27   ERROR_SECTOR_NOT_FOUND
  8188.           Sector not found.
  8189.  
  8190.   28   ERROR_OUT_OF_PAPER
  8191.           Printer is out of paper.
  8192.  
  8193.   29   ERROR_WRITE FAULT
  8194.           Write fault.
  8195.  
  8196.   30   ERROR_READ_FAULT
  8197.           Read fault.
  8198.  
  8199.   31   ERROR_GEN_FAILURE
  8200.           General failure.
  8201.  
  8202.   32   ERROR_SHARING_VIOLATION
  8203.           Sharing violation.
  8204.  
  8205.   33   ERROR_LOCK_VIOLATION
  8206.           Lock violation.
  8207.  
  8208.   34   ERROR_WRONG_DISK
  8209.           Invalid disk change.
  8210.  
  8211.   35   ERROR_FCB_UNAVAILABLE
  8212.           FCB unavailable.
  8213.  
  8214.   36   ERROR_SHARING_BUFFER_EXCEEDED
  8215.           Sharing buffer overflow.
  8216.  
  8217.   37   ERROR_CODE_PAGE_MISMATCHED
  8218.           Code page does not match.
  8219.  
  8220.   38   ERROR_HANDLE_EOF
  8221.           End of file reached.
  8222.  
  8223.   39   ERROR_HANDLE_DISK_FULL
  8224.           Disk is full.
  8225.  
  8226.   40-49   Reserved.
  8227.  
  8228.  
  8229.   50   ERROR_NOT_SUPPORTED
  8230.           Network request not supported.
  8231.  
  8232.   51   ERROR_REM_NOT_LIST
  8233.           Remote network node is not online.
  8234.  
  8235.   52   ERROR_DUP_NAME
  8236.           Duplicate file name in network.
  8237.  
  8238.   53   ERROR_BAD_NETPATH
  8239.           Network path not found.
  8240.  
  8241.   54   ERROR_NETWORK_BUSY
  8242.           Network is busy.
  8243.  
  8244.   55   ERROR_DEV_NOT_EXIST
  8245.           Device is not installed in network.
  8246.  
  8247.   56   ERROR_TOO_MANY_CMDS
  8248.           Network command limit reached.
  8249.  
  8250.   57   ERROR_ADAP_HDW_ERR
  8251.           Network adapter hardware error.
  8252.  
  8253.   58   ERROR_BAD_NET_RESP
  8254.           Incorrect response in network.
  8255.  
  8256.   59   ERROR_UNEXP_NET_ERR
  8257.           Unexpected error in network.
  8258.  
  8259.   60   ERROR_BAD_REM_ADAP
  8260.           Remote network adapter error.
  8261.  
  8262.   61   ERROR_PRINTQ_FULL
  8263.           Network printer queue is full.
  8264.  
  8265.   62   ERROR_NO_SPOOL_SPACE
  8266.           No space in print spool file.
  8267.  
  8268.   63   ERROR_PRINT_CANCELLED
  8269.           Print spool file deleted.
  8270.  
  8271.   64   ERROR_NETNAME_DELETED
  8272.           Network name deleted.
  8273.  
  8274.   65   ERROR_NETWORK_ACCESS_DENIED
  8275.           Access to network denied.
  8276.  
  8277.   66   ERROR_BAD_DEV_TYPE
  8278.           Device type invalid for network.
  8279.  
  8280.   67   ERROR_BAD_NET_NAME
  8281.           Network name not found.
  8282.  
  8283.   68   ERROR_TOO_MANY_NAMES
  8284.           Network name limit exceeded.
  8285.  
  8286.   69   ERROR_TOO_MANY_SESS
  8287.           Network session limit exceeded.
  8288.  
  8289.   70   ERROR_SHARING_PAUSED
  8290.           Temporary pause in network.
  8291.  
  8292.   71   ERROR_REQ_NOT_ACCEP
  8293.           Network request denied.
  8294.  
  8295.   72   ERROR_REDIR_PAUSED
  8296.           Pause in network print disk redirection.
  8297.  
  8298.   73   ERROR_SBCS_ATT_WRITE_PROT
  8299.           Attempted write on protected disk.
  8300.  
  8301.   74   ERROR_SBCS_GENERAL_FAILURE
  8302.           General failure, single-byte character set.
  8303.  
  8304.   75-79   Reserved.
  8305.  
  8306.  
  8307.   80   ERROR_FILE_EXISTS
  8308.           File exists.
  8309.  
  8310.   81   ERROR_DUP_FCB
  8311.           Reserved.
  8312.  
  8313.   82   ERROR_CANNOT_MAKE
  8314.           Cannot make directory entry.
  8315.  
  8316.   83   ERROR_FAIL_I24
  8317.           Failure on INT 24.
  8318.  
  8319.   84   ERROR_OUT_OF_STRUCTURES
  8320.           Too many redirections.
  8321.  
  8322.   85   ERROR_ALREADY_ASSIGNED
  8323.           Duplicate redirection.
  8324.  
  8325.   86   ERROR_INVALID_PASSWORD
  8326.           Invalid password.
  8327.  
  8328.   87   ERROR_INVALID_PARAMETER
  8329.           Invalid parameter.
  8330.  
  8331.   88   ERROR_NET_WRITE_FAULT
  8332.           Network device fault.
  8333.  
  8334.   89   ERROR_NO_PROC_SLOTS
  8335.           No process slots available.
  8336.  
  8337.   90   ERROR_NOT_FROZEN
  8338.           System error.
  8339.  
  8340.   91   ERR_TSTOVFL
  8341.           Timer service table overflow.
  8342.  
  8343.   92   ERR_TSTDUP
  8344.           Timer service table duplicate.
  8345.  
  8346.   93   ERROR_NO_ITEMS
  8347.           No items to work on.
  8348.  
  8349.   95   ERROR_INTERRUPT
  8350.           Interrupted system call.
  8351.  
  8352.   99   ERROR_DEVICE_IN_USE
  8353.           Device in use.
  8354.  
  8355.   100   ERROR_TOO_MANY_SEMAPHORES
  8356.           User/system open semaphore limit reached.
  8357.  
  8358.   101   ERROR_EXCL_SEM_ALREADY_OWNED
  8359.           Exclusive semaphore already owned.
  8360.  
  8361.   102   ERROR_SEM_IS_SET
  8362.           DosCloseSem found semaphore set.
  8363.  
  8364.   103   ERROR_TOO_MANY_SEM_REQUESTS
  8365.           Too many exclusive semaphore requests.
  8366.  
  8367.   104   ERROR_INVALID_AT_INTERRUPT_TIME
  8368.           Operation invalid at interrupt time.
  8369.  
  8370.   105   ERROR_SEM_OWNER_DIED
  8371.           Previous semaphore owner terminated without freeing semaphore.
  8372.  
  8373.   106   ERROR_SEM_USER_LIMIT
  8374.           Semaphore limit exceeded.
  8375.  
  8376.   107   ERROR_DISK_CHANGE
  8377.           Insert drive B disk into drive A.
  8378.  
  8379.   108   ERROR_DRIVE_LOCKED
  8380.           Drive locked by another process.
  8381.  
  8382.   109   ERROR_BROKEN_PIPE
  8383.           Write on pipe with no reader.
  8384.  
  8385.   110   ERROR_OPEN_FAILED
  8386.           Open/create failed due to explicit fail command.
  8387.  
  8388.   111   ERROR_BUFFER_OVERFLOW
  8389.           Buffer passed to system call too small to hold return data.
  8390.  
  8391.   112   ERROR_DISK_FULL
  8392.           Not enough space on the disk.
  8393.  
  8394.   113   ERROR_NO_MORE_SEARCH_HANDLES
  8395.           Cannot allocate another search structure and handle.
  8396.  
  8397.   114   ERROR_INVALID_TARGET_HANDLE
  8398.           Target handle in DosDupHandle invalid.
  8399.  
  8400.   115   ERROR_PROTECTION_VIOLATION
  8401.           Invalid user virtual address.
  8402.  
  8403.   116   ERROR_VIOKBD_REQUEST
  8404.           Error on display write or keyboard read.
  8405.  
  8406.   117   ERROR_INVALID_CATEGORY
  8407.           Category for DevIOCtl not defined.
  8408.  
  8409.   118   ERROR_INVALID_VERIFY_SWITCH
  8410.           Invalid value passed for verify flag.
  8411.  
  8412.   119   ERROR_BAD_DRIVER_LEVEL
  8413.           Level four driver not found.
  8414.  
  8415.   120   ERROR_CALL_NOT_IMPLEMENTED
  8416.           Invalid function called.
  8417.  
  8418.   121   ERROR_SEM_TIMEOUT
  8419.           Time-out occurred from semaphore API function.
  8420.  
  8421.   122   ERROR_INSUFFICIENT_BUFFER
  8422.           Data buffer too small.
  8423.  
  8424.   123   ERROR_INVALID_NAME
  8425.           Illegal character or invalid file-system name.
  8426.  
  8427.   124   ERROR_INVALID_LEVEL
  8428.           Non-implemented level for information retrieval or setting.
  8429.  
  8430.   125   ERROR_NO_VOLUME_LABEL
  8431.           No volume label found with DosQueryFSInfo function.
  8432.  
  8433.   126   ERROR_MOD_NOT_FOUND
  8434.           Module handle not found with DosQueryProcAddr(),
  8435.           DosQueryModAddr().
  8436.  
  8437.   127   ERROR_PROC_NOT_FOUND
  8438.           Procedure address not found with DosQueryProcAddr().
  8439.  
  8440.   128   ERROR_WAIT_NO_CHILDREN
  8441.           DosWaitChild finds no children.
  8442.  
  8443.   129   ERROR_CHILD_NOT_COMPLETE
  8444.           DosWaitChild children not terminated.
  8445.  
  8446.   130   ERROR_DIRECT_ACCESS_HANDLE
  8447.           Handle operation invalid for direct disk-access handles.
  8448.  
  8449.   131   ERROR_NEGATIVE_SEEK
  8450.           Attempting seek to negative offset.
  8451.  
  8452.   132   ERROR_SEEK_ON_DEVICE
  8453.           Application trying to seek on device or pipe.
  8454.  
  8455.   133   ERROR_IS_JOIN_TARGET
  8456.           Drive has previously joined drives.
  8457.  
  8458.   134   ERROR_IS_JOINED
  8459.           Drive is already joined.
  8460.  
  8461.   135   ERROR_IS_SUBSTED
  8462.           Drive is already substituted.
  8463.  
  8464.   136   ERROR_NOT_JOINED
  8465.           Cannot delete drive that is not joined.
  8466.  
  8467.   137   ERROR_NOT_SUBSTED
  8468.           Cannot delete drive that is not substituted.
  8469.  
  8470.   138   ERROR_JOIN_TO_JOIN
  8471.           Cannot join to a joined drive.
  8472.  
  8473.   139   ERROR_SUBST_TO_SUBST
  8474.           Cannot substitute to a substituted drive.
  8475.  
  8476.   140   ERROR_JOIN_TO_SUBST
  8477.           Cannot join to a substituted drive.
  8478.  
  8479.   141   ERROR_SUBST_TO_JOIN
  8480.           Cannot substitute to a joined drive.
  8481.  
  8482.   142   ERROR_BUSY_DRIVE
  8483.           Specified drive is busy.
  8484.  
  8485.   143   ERROR_SAME_DRIVE
  8486.           Cannot join or substitute a drive to a directory on the same drive.
  8487.  
  8488.   144   ERROR_DIR_NOT_ROOT
  8489.           Directory must be a subdirectory of the root.
  8490.  
  8491.   145   ERROR_DIR_NOT_EMPTY
  8492.           Directory must be empty to use join command.
  8493.  
  8494.   146   ERROR_IS_SUBST_PATH
  8495.           Path specified is being used in a substitute.
  8496.  
  8497.   147   ERROR_IS_JOIN_PATH
  8498.           Path specified is being used in a join.
  8499.  
  8500.   148   ERROR_PATH_BUSY
  8501.           Path specified is being used by another process.
  8502.  
  8503.   149   ERROR_IS_SUBST_TARGET
  8504.           Cannot join or substitute a drive that has a directory that is the
  8505.           target of a previous substitute.
  8506.  
  8507.   150   ERROR_SYSTEM_TRACE
  8508.           System trace error.
  8509.  
  8510.   151   ERROR_INVALID_EVENT_COUNT
  8511.           DosWaitMuxWaitSem errors.
  8512.  
  8513.   152   ERROR_TOO_MANY_MUXWAITERS
  8514.           System limit of 100 entries reached.
  8515.  
  8516.   153   ERROR_INVALID_LIST_FORMAT
  8517.           Invalid list format.
  8518.  
  8519.   154   ERROR_LABEL_TOO_LONG
  8520.           Volume label too big.
  8521.  
  8522.   155   ERROR_TOO_MANY_TCBS
  8523.           Cannot create another TCB.
  8524.  
  8525.   156   ERROR_SIGNAL_REFUSED
  8526.           Signal refused.
  8527.  
  8528.   157   ERROR_DISCARDED
  8529.           Segment is discarded.
  8530.  
  8531.   158   ERROR_NOT_LOCKED
  8532.           Segment is not locked.
  8533.  
  8534.   159   ERROR_BAD_THREADID_ADDR
  8535.           Invalid thread-identity address.
  8536.  
  8537.   160   ERROR_BAD_ARGUMENTS
  8538.           Invalid environment pointer.
  8539.  
  8540.   161   ERROR_BAD_PATHNAME
  8541.           Invalid path name passed to exec.
  8542.  
  8543.   162   ERROR_SIGNAL_PENDING
  8544.           Signal already pending.
  8545.  
  8546.   163   ERROR_UNCERTAIN_MEDIA
  8547.           Error with INT 24 mapping.
  8548.  
  8549.   164   ERROR_MAX_THRDS_REACHED
  8550.           No more process slots.
  8551.  
  8552.   165   ERROR_MONITORS_NOT_SUPPORTED
  8553.           Error with INT 24 mapping.
  8554.  
  8555.   166   ERROR_UNC_DRIVER_NOT_INSTALLED
  8556.           Default redirection return code.
  8557.  
  8558.   167   ERROR_LOCK_FAILED
  8559.           Locking failed.
  8560.  
  8561.   168   ERROR_SWAPIO_FAILED
  8562.           Swap I/O failed.
  8563.  
  8564.   169   ERROR_SWAPIN_FAILED
  8565.           Swap in failed.
  8566.  
  8567.   170   ERROR_BUSY
  8568.           Segment is busy.
  8569.  
  8570.   171-172   Reserved.
  8571.  
  8572.  
  8573.   173   ERROR_CANCEL_VIOLATION
  8574.           A lock request is not outstanding for the specified file range, or the
  8575.           range length is zero.
  8576.  
  8577.   174   ERROR_ATOMIC_LOCK_NOT_SUPPORTED
  8578.           The file-system driver (FSD) does not support atomic lock operations.
  8579.           Versions of OS/2 prior to version 2.00 do not support atomic lock
  8580.           operations.
  8581.  
  8582.   175   ERROR_READ_LOCKS_NOT_SUPPORTED
  8583.           The file system driver (FSD) does not support shared read locks.
  8584.  
  8585.   176-179   Reserved.
  8586.  
  8587.  
  8588.   180   ERROR_INVALID_SEGMENT_NUMBER
  8589.           Invalid segment number.
  8590.  
  8591.   181   ERROR_INVALID_CALLGATE
  8592.           Invalid call gate.
  8593.  
  8594.   182   ERROR_INVALID_ORDINAL
  8595.           Invalid ordinal.
  8596.  
  8597.   183   ERROR_ALREADY_EXISTS
  8598.           Shared segment already exists.
  8599.  
  8600.   184   ERROR_NO_CHILD_PROCESS
  8601.           No child process to wait for.
  8602.  
  8603.   185   ERROR_CHILD_ALIVE_NOWAIT
  8604.           NoWait specified and child alive.
  8605.  
  8606.   186   ERROR_INVALID_FLAG_NUMBER
  8607.           Invalid flag number.
  8608.  
  8609.   187   ERROR_SEM_NOT_FOUND
  8610.           Semaphore does not exist.
  8611.  
  8612.   188   ERROR_INVALID_STARTING_CODESEG
  8613.           Invalid starting code segment, incorrect END (label) directive.
  8614.  
  8615.   189   ERROR_INVALID_STACKSEG
  8616.           Invalid stack segment.
  8617.  
  8618.   190   ERROR_INVALID_MODULETYPE
  8619.           Invalid module type - dynamic-link library file cannot be used as an
  8620.           application. Application cannot be used as a dynamic-link library.
  8621.  
  8622.   191   ERROR_INVALID_EXE_SIGNATURE
  8623.           Invalid EXE signature - file is a DOS mode program or an improper
  8624.           program.
  8625.  
  8626.   192   ERROR_EXE_MARKED_INVALID
  8627.           EXE marked invalid - link detected errors when the application was
  8628.           created.
  8629.  
  8630.   193   ERROR_BAD_EXE_FORMAT
  8631.           Invalid EXE format - file is a DOS mode program or an improper
  8632.           program.
  8633.  
  8634.   194   ERROR_ITERATED_DATA_EXCEEDS_64k
  8635.           Iterated data exceeds 64KB - there is more than 64KB of data in one
  8636.           of the segments of the file.
  8637.  
  8638.   195   ERROR_INVALID_MINALLOCSIZE
  8639.           Invalid minimum allocation size - the size is specified to be less than
  8640.           the size of the segment data in the file.
  8641.  
  8642.   196   ERROR_DYNLINK_FROM_INVALID_RING
  8643.           Dynamic link from invalid privilege level - privilege level 2 routine
  8644.           cannot link to dynamic-link libraries.
  8645.  
  8646.   197   ERROR_IOPL_NOT_ENABLED
  8647.           IOPL not enabled - IOPL set to NO in CONFIG.SYS.
  8648.  
  8649.   198   ERROR_INVALID_SEGDPL
  8650.           Invalid segment descriptor privilege level - can only have privilege
  8651.           levels of 2 and 3.
  8652.  
  8653.   199   ERROR_AUTODATASEG_EXCEEDS_64k
  8654.           Automatic data segment exceeds 64KB.
  8655.  
  8656.   200   ERROR_RING2SEG_MUST_BE_MOVABLE
  8657.           Privilege level 2 segment must be movable.
  8658.  
  8659.   201   ERROR_RELOC_CHAIN_XEEDS_SEGLIM
  8660.           Relocation chain exceeds segment limit.
  8661.  
  8662.   202   ERROR_INFLOOP_IN_RELOC_CHAIN
  8663.           Infinite loop in relocation chain segment.
  8664.  
  8665.   203   ERROR_ENVVAR_NOT_FOUND
  8666.           Environment variable not found.
  8667.  
  8668.   204   ERROR_NOT_CURRENT_CTRY
  8669.           Not current country.
  8670.  
  8671.   205   ERROR_NO_SIGNAL_SENT
  8672.           No signal sent - no process in the command subtree has a signal
  8673.           handler.
  8674.  
  8675.   206   ERROR_FILENAME_EXCED_RANGE
  8676.           File name or extension is greater than 8.3 characters.
  8677.  
  8678.   207   ERROR_RING2_STACK_IN_USE
  8679.           Privilege level 2 stack is in use.
  8680.  
  8681.   208   ERROR_META_EXPANSION_TOO_LONG
  8682.           Meta (global) expansion is too long.
  8683.  
  8684.   209   ERROR_INVALID_SIGNAL_NUMBER
  8685.           Invalid signal number.
  8686.  
  8687.   210   ERROR_THREAD_1_INACTIVE
  8688.           Inactive thread.
  8689.  
  8690.   211   ERROR_INFO_NOT_AVAIL
  8691.           File system information is not available for this file.
  8692.  
  8693.   212   ERROR_LOCKED
  8694.           Locked error.
  8695.  
  8696.   213   ERROR_BAD_DYNALINK
  8697.           Attempted to execute a non-family API in DOS mode.
  8698.  
  8699.   214   ERROR_TOO_MANY_MODULES
  8700.           Too many modules.
  8701.  
  8702.   215   ERROR_NESTING_NOT_ALLOWED
  8703.           Nesting is not allowed.
  8704.  
  8705.   217   ERROR_ZOMBIE_PROCESS
  8706.           Zombie process.
  8707.  
  8708.   218   ERROR_STACK_IN_HIGH_MEMORY
  8709.           Stack is in high memory.
  8710.  
  8711.   219   ERROR_INVALID_EXITROUTINE_RING
  8712.           Invalid exit routine ring.
  8713.  
  8714.   220   ERROR_GETBUF_FAILED
  8715.           Get buffer failed.
  8716.  
  8717.   221   ERROR_FLUSHBUF_FAILED
  8718.           Flush buffer failed.
  8719.  
  8720.   222   ERROR_TRANSFER_TOO_LONG
  8721.           Transfer is too long.
  8722.  
  8723.   224   ERROR_SMG_NO_TARGET_WINDOW
  8724.           The application window was created without the FCF_TASKLIST
  8725.           style, or the application window not yet been created or has already
  8726.           been destroyed.
  8727.  
  8728.   228   ERROR_NO_CHILDREN
  8729.           No child process.
  8730.  
  8731.   229   ERROR_INVALID_SCREEN_GROUP
  8732.           Invalid session.
  8733.  
  8734.   230   ERROR_BAD_PIPE
  8735.           Non-existent pipe or invalid operation.
  8736.  
  8737.   231   ERROR_PIPE_BUSY
  8738.           Pipe is busy.
  8739.  
  8740.   232   ERROR_NO_DATA
  8741.           No data available on non-blocking read.
  8742.  
  8743.   233   ERROR_PIPE_NOT_CONNECTED
  8744.           Pipe was disconnected by server.
  8745.  
  8746.   234   ERROR_MORE_DATA
  8747.           More data is available.
  8748.  
  8749.   240   ERROR_VC_DISCONNECTED
  8750.           Session was dropped due to errors.
  8751.  
  8752.   250   ERROR_CIRCULARITY_REQUESTED
  8753.           Renaming a directory that would cause a circularity problem.
  8754.  
  8755.   251   ERROR_DIRECTORY_IN_CDS
  8756.           Renaming a directory that is in use.
  8757.  
  8758.   252   ERROR_INVALID_FSD_NAME
  8759.           Trying to access nonexistent FSD.
  8760.  
  8761.   253   ERROR_INVALID_PATH
  8762.           Invalid pseudo device.
  8763.  
  8764.   254   ERROR_INVALID_EA_NAME
  8765.           Invalid character in name, or invalid cbName.
  8766.  
  8767.   255   ERROR_EA_LIST_INCONSISTENT
  8768.           List does not match its size, or there are invalid EAs in the list.
  8769.  
  8770.   256   ERROR_EA_LIST_TOO_LONG
  8771.           FEAList is longer than 64K-1 bytes.
  8772.  
  8773.   257   ERROR_NO_META_MATCH
  8774.           String does not match expression.
  8775.  
  8776.   259   ERROR_NO_MORE_ITEMS
  8777.           DosQueryFSAttach ordinal query.
  8778.  
  8779.   260   ERROR_SEARCH_STRUC_REUSED
  8780.           DOS mode findfirst/next search structure reused.
  8781.  
  8782.   261   ERROR_CHAR_NOT_FOUND
  8783.           Character not found.
  8784.  
  8785.   262   ERROR_TOO_MUCH_STACK
  8786.           Stack request exceeds system limit.
  8787.  
  8788.   263   ERROR_INVALID_ATTR
  8789.           Invalid attribute.
  8790.  
  8791.   264   ERROR_INVALID_STARTING_RING
  8792.           Invalid starting ring.
  8793.  
  8794.   265   ERROR_INVALID_DLL_INIT_RING
  8795.           Invalid DLL INIT ring.
  8796.  
  8797.   266   ERROR_CANNOT_COPY
  8798.           Cannot copy.
  8799.  
  8800.   267   ERROR_DIRECTORY
  8801.           Used by DOSCOPY in doscall1.
  8802.  
  8803.   268   ERROR_OPLOCKED_FILE
  8804.           Oplocked file.
  8805.  
  8806.   269   ERROR_OPLOCK_THREAD_EXISTS
  8807.           Oplock thread exists.
  8808.  
  8809.   270   ERROR_VOLUME_CHANGED
  8810.           Volume changed.
  8811.  
  8812.   271-273   Reserved.
  8813.  
  8814.  
  8815.   274   ERROR_ALREADY_SHUTDOWN
  8816.           System is already shut down.
  8817.  
  8818.   275   ERROR_EAS_DIDNT_FIT
  8819.           Buffer is not big enough to hold the EAs.
  8820.  
  8821.   276   ERROR_EA_FILE_CORRUPT
  8822.           EA file has been damaged.
  8823.  
  8824.   277   ERROR_EA_TABLE_FULL
  8825.           EA table is full.
  8826.  
  8827.   278   ERROR_INVALID_EA_HANDLE
  8828.           EA handle is invalid.
  8829.  
  8830.   279   ERROR_NO_CLUSTER
  8831.           No cluster.
  8832.  
  8833.   280   ERROR_CREATE_EA_FILE
  8834.           Cannot create the EA file.
  8835.  
  8836.   281   ERROR_CANNOT_OPEN_EA_FILE
  8837.           Cannot open the EA file.
  8838.  
  8839.   282   ERROR_EAS_NOT_SUPPORTED
  8840.           Destination file system does not support EAs.
  8841.  
  8842.   283   ERROR_NEED_EAS_FOUND
  8843.           Destination file system does not support EAs, and the source file's
  8844.           EAs contain a need EA.
  8845.  
  8846.   284   ERROR_DUPLICATE_HANDLE
  8847.           The handle already exists.
  8848.  
  8849.   285   ERROR_DUPLICATE_NAME
  8850.           The name already exists.
  8851.  
  8852.   286   ERROR_EMPTY_MUXWAIT
  8853.           The list of semaphores in a muxwait semaphore is empty.
  8854.  
  8855.   287   ERROR_MUTEX_OWNED
  8856.           The calling thread owns one or more of the mutex semaphores in the
  8857.           list.
  8858.  
  8859.   288   ERROR_NOT_OWNER
  8860.           Caller does not own the semaphore.
  8861.  
  8862.   289   ERROR_PARAM_TOO_SMALL
  8863.           Parameter is not large enough to contain all of the semaphore
  8864.           records in the muxwait semaphore.
  8865.  
  8866.   290   ERROR_TOO_MANY_HANDLES
  8867.           Limit reached for number of handles.
  8868.  
  8869.   291   ERROR_TOO_MANY_OPENS
  8870.           There are too many files or semaphores open.
  8871.  
  8872.   292   ERROR_WRONG_TYPE
  8873.           Attempted to create wrong type of semaphore.
  8874.  
  8875.   293   ERROR_UNUSED_CODE
  8876.           Code is not used.
  8877.  
  8878.   294   ERROR_THREAD_NOT_TERMINATED
  8879.           Thread has not terminated.
  8880.  
  8881.   295   ERROR_INIT_ROUTINE_FAILED
  8882.           Initialization routine failed.
  8883.  
  8884.   296   ERROR_MODULE_IN_USE
  8885.           Module is in use.
  8886.  
  8887.   297   ERROR_NOT_ENOUGH_WATCHPOINTS
  8888.           There are not enough watchpoints.
  8889.  
  8890.   298   ERROR_TOO_MANY_POSTS
  8891.           Post count limit was reached for an event semaphore.
  8892.  
  8893.   299   ERROR_ALREADY_POSTED
  8894.           Event semaphore is already posted.
  8895.  
  8896.   300   ERROR_ALREADY_RESET
  8897.           Event semaphore is already reset.
  8898.  
  8899.   301   ERROR_SEM_BUSY
  8900.           Semaphore is busy.
  8901.  
  8902.   302   Reserved
  8903.  
  8904.  
  8905.   303   ERROR_INVALID_PROCID
  8906.           Invalid process identity.
  8907.  
  8908.   304   ERROR_INVALID_PDELTA
  8909.           Invalid priority delta.
  8910.  
  8911.   305   ERROR_NOT_DESCENDANT
  8912.           Not descendant.
  8913.  
  8914.   306   ERROR_NOT_SESSION_MANAGER
  8915.           Requestor not session manager.
  8916.  
  8917.   307   ERROR_INVALID_PCLASS
  8918.           Invalid P class.
  8919.  
  8920.   308   ERROR_INVALID_SCOPE
  8921.           Invalid scope.
  8922.  
  8923.   309   ERROR_INVALID_THREADID
  8924.           Invalid thread identity.
  8925.  
  8926.   310   ERROR_DOSSUB_SHRINK
  8927.           Cannot shrink segment - DosSubSetMem.
  8928.  
  8929.   311   ERROR_DOSSUB_NOMEM
  8930.           No memory to satisfy request - DosSubAllocMem.
  8931.  
  8932.   312   ERROR_DOSSUB_OVERLAP
  8933.           Overlap of the specified block with a block of allocated memory -
  8934.           DosSubFreeMem.
  8935.  
  8936.   313   ERROR_DOSSUB_BADSIZE
  8937.           Invalid size parameter - DosSubAllocMem or DosSubFreeMem.
  8938.  
  8939.   314   ERROR_DOSSUB_BADFLAG
  8940.           Invalid flag parameter - DosSubSetMem.
  8941.  
  8942.   315   ERROR_DOSSUB_BADSELECTOR
  8943.           Invalid segment selector.
  8944.  
  8945.   316   ERROR_MR_MSG_TOO_LONG
  8946.           Message too long for buffer.
  8947.  
  8948.   317   ERROR_MR_MID_NOT_FOUND
  8949.           Message identity number not found.
  8950.  
  8951.   318   ERROR_MR_UN_ACC_MSGF
  8952.           Unable to access message file.
  8953.  
  8954.   319   ERROR_MR_INV_MSGF_FORMAT
  8955.           Invalid message file format.
  8956.  
  8957.   320   ERROR_MR_INV_IVCOUNT
  8958.           Invalid insertion variable count.
  8959.  
  8960.   321   ERROR_MR_UN_PERFORM
  8961.           Unable to perform function.
  8962.  
  8963.   322   ERROR_TS_WAKEUP
  8964.           Unable to wake up.
  8965.  
  8966.   323   ERROR_TS_SEMHANDLE
  8967.           Invalid system semaphore.
  8968.  
  8969.   324   ERROR_TS_NOTIMER
  8970.           No timers available.
  8971.  
  8972.   326   ERROR_TS_HANDLE
  8973.           Invalid timer handle.
  8974.  
  8975.   327   ERROR_TS_DATETIME
  8976.           Date or time invalid.
  8977.  
  8978.   328   ERROR_SYS_INTERNAL
  8979.           Internal system error.
  8980.  
  8981.   329   ERROR_QUE_CURRENT_NAME
  8982.           Current queue name does not exist.
  8983.  
  8984.   330   ERROR_QUE_PROC_NOT_OWNED
  8985.           Current process does not own queue.
  8986.  
  8987.   331   ERROR_QUE_PROC_OWNED
  8988.           Current process owns queue.
  8989.  
  8990.   332   ERROR_QUE_DUPLICATE
  8991.           Duplicate queue name.
  8992.  
  8993.   333   ERROR_QUE_ELEMENT_NOT_EXIST
  8994.           Queue element does not exist.
  8995.  
  8996.   334   ERROR_QUE_NO_MEMORY
  8997.           Inadequate queue memory.
  8998.  
  8999.   335   ERROR_QUE_INVALID_NAME
  9000.           Invalid queue name.
  9001.  
  9002.   336   ERROR_QUE_INVALID_PRIORITY
  9003.           Invalid queue priority parameter.
  9004.  
  9005.   337   ERROR_QUE_INVALID_HANDLE
  9006.           Invalid queue handle.
  9007.  
  9008.   338   ERROR_QUE_LINK_NOT_FOUND
  9009.           Queue link not found.
  9010.  
  9011.   339   ERROR_QUE_MEMORY_ERROR
  9012.           Queue memory error.
  9013.  
  9014.   340   ERROR_QUE_PREV_AT_END
  9015.           Previous queue element was at end of queue.
  9016.  
  9017.   341   ERROR_QUE_PROC_NO_ACCESS
  9018.           Process does not have access to queues.
  9019.  
  9020.   342   ERROR_QUE_EMPTY
  9021.           Queue is empty.
  9022.  
  9023.   343   ERROR_QUE_NAME_NOT_EXIST
  9024.           Queue name does not exist.
  9025.  
  9026.   344   ERROR_QUE_NOT_INITIALIZED
  9027.           Queues not initialized.
  9028.  
  9029.   345   ERROR_QUE_UNABLE_TO_ACCESS
  9030.           Unable to access queues.
  9031.  
  9032.   346   ERROR_QUE_UNABLE_TO_ADD
  9033.           Unable to add new queue.
  9034.  
  9035.   347   ERROR_QUE_UNABLE_TO_INIT
  9036.           Unable to initialize queues.
  9037.  
  9038.   349   ERROR_VIO_INVALID_MASK
  9039.           Invalid function replaced.
  9040.  
  9041.   350   ERROR_VIO_PTR
  9042.           Invalid pointer to parameter.
  9043.  
  9044.   351   ERROR_VIO_APTR
  9045.           Invalid pointer to attribute.
  9046.  
  9047.   352   ERROR_VIO_RPTR
  9048.           Invalid pointer to row.
  9049.  
  9050.   353   ERROR_VIO_CPTR
  9051.           Invalid pointer to column.
  9052.  
  9053.   354   ERROR_VIO_LPTR
  9054.           Invalid pointer to length.
  9055.  
  9056.   355   ERROR_VIO_MODE
  9057.           Unsupported screen mode.
  9058.  
  9059.   356   ERROR_VIO_WIDTH
  9060.           Invalid cursor width value.
  9061.  
  9062.   357   ERROR_VIO_ATTR
  9063.           Invalid cursor attribute value.
  9064.  
  9065.   358   ERROR_VIO_ROW
  9066.           Invalid row value.
  9067.  
  9068.   359   ERROR_VIO_COL
  9069.           Invalid column value.
  9070.  
  9071.   360   ERROR_VIO_TOPROW
  9072.           Invalid TopRow value.
  9073.  
  9074.   361   ERROR_VIO_BOTROW
  9075.           Invalid BotRow value.
  9076.  
  9077.   362   ERROR_VIO_RIGHTCOL
  9078.           Invalid right column value.
  9079.  
  9080.   363   ERROR_VIO_LEFTCOL
  9081.           Invalid left column value.
  9082.  
  9083.   364   ERROR_SCS_CALL
  9084.           Call issued by other than session manager.
  9085.  
  9086.   365   ERROR_SCS_VALUE
  9087.           Value is not for save or restore.
  9088.  
  9089.   366   ERROR_VIO_WAIT_FLAG
  9090.           Invalid wait flag setting.
  9091.  
  9092.   367   ERROR_VIO_UNLOCK
  9093.           Screen not previously locked.
  9094.  
  9095.   368   ERROR_SGS_NOT_SESSION_MGR
  9096.           Caller not session manager.
  9097.  
  9098.   369   ERROR_SMG_INVALID_SGID
  9099.           Invalid session identity.
  9100.  
  9101.   369   ERROR_SMG_INVALID_SESSION_ID
  9102.           Invalid session ID.
  9103.  
  9104.   370   ERROR_SMG_NOSG
  9105.           No sessions available.
  9106.  
  9107.   370   ERROR_SMG_NO_SESSIONS
  9108.           No sessions available.
  9109.  
  9110.   371   ERROR_SMG_GRP_NOT_FOUND
  9111.           Session not found.
  9112.  
  9113.   371   ERROR_SMG_SESSION_NOT_FOUND
  9114.           Session not found.
  9115.  
  9116.   372   ERROR_SMG_SET_TITLE
  9117.           Title sent by shell or parent cannot be changed.
  9118.  
  9119.   373   ERROR_KBD_PARAMETER
  9120.           Invalid parameter to keyboard.
  9121.  
  9122.   374   ERROR_KBD_NO_DEVICE
  9123.           No device.
  9124.  
  9125.   375   ERROR_KBD_INVALID_IOWAIT
  9126.           Invalid I/O wait specified.
  9127.  
  9128.   376   ERROR_KBD_INVALID_LENGTH
  9129.           Invalid length for keyboard.
  9130.  
  9131.   377   ERROR_KBD_INVALID_ECHO_MASK
  9132.           Invalid echo mode mask.
  9133.  
  9134.   378   ERROR_KBD_INVALID_INPUT_MASK
  9135.           Invalid input mode mask.
  9136.  
  9137.   379   ERROR_MON_INVALID_PARMS
  9138.           Invalid parameters to DosMon.
  9139.  
  9140.   380   ERROR_MON_INVALID_DEVNAME
  9141.           Invalid device name string.
  9142.  
  9143.   381   ERROR_MON_INVALID_HANDLE
  9144.           Invalid device handle.
  9145.  
  9146.   382   ERROR_MON_BUFFER_TOO_SMALL
  9147.           Buffer too small.
  9148.  
  9149.   383   ERROR_MON_BUFFER_EMPTY
  9150.           Buffer is empty.
  9151.  
  9152.   384   ERROR_MON_DATA_TOO_LARGE
  9153.           Data record is too large.
  9154.  
  9155.   385   ERROR_MOUSE_NO_DEVICE
  9156.           Mouse device closed (invalid device handle).
  9157.  
  9158.   386   ERROR_MOUSE_INV_HANDLE
  9159.           Mouse device closed (invalid device handle).
  9160.  
  9161.   387   ERROR_MOUSE_INV_PARMS
  9162.           Parameters invalid for display mode.
  9163.  
  9164.   388   ERROR_MOUSE_CANT_RESET
  9165.           Function assigned and cannot be reset.
  9166.  
  9167.   389   ERROR_MOUSE_DISPLAY_PARMS
  9168.           Parameters invalid for display mode.
  9169.  
  9170.   390   ERROR_MOUSE_INV_MODULE
  9171.           Module not valid.
  9172.  
  9173.   391   ERROR_MOUSE_INV_ENTRY_PT
  9174.           Entry point not valid.
  9175.  
  9176.   392   ERROR_MOUSE_INV_MASK
  9177.           Function mask invalid.
  9178.  
  9179.   393   NO_ERROR_MOUSE_NO_DATA
  9180.           No valid data.
  9181.  
  9182.   394   NO_ERROR_MOUSE_PTR_DRAWN
  9183.           Pointer drawn.
  9184.  
  9185.   395   ERROR_INVALID_FREQUENCY
  9186.           Invalid frequency for beep.
  9187.  
  9188.   396   ERROR_NLS_NO_COUNTRY_FILE
  9189.           Cannot find COUNTRY.SYS file.
  9190.  
  9191.   397   ERROR_NLS_OPEN_FAILED
  9192.           Cannot open COUNTRY.SYS file.
  9193.  
  9194.   398   ERROR_NLS_NO_CTRY_CODE
  9195.           Country code not found.
  9196.  
  9197.   398   ERROR_NO_COUNTRY_OR_CODEPAGE
  9198.           Country code not found.
  9199.  
  9200.   399   ERROR_NLS_TABLE_TRUNCATED
  9201.           Table returned information truncated, buffer is too small.
  9202.  
  9203.   400   ERROR_NLS_BAD_TYPE
  9204.           Selected type does not exist.
  9205.  
  9206.   401   ERROR_NLS_TYPE_NOT_FOUND
  9207.           Selected type is not in file.
  9208.  
  9209.   402   ERROR_VIO_SMG_ONLY
  9210.           Valid from session manager only.
  9211.  
  9212.   403   ERROR_VIO_INVALID_ASCIIZ
  9213.           Invalid ASCIIZ length.
  9214.  
  9215.   404   ERROR_VIO_DEREGISTER
  9216.           VioDeRegister not allowed.
  9217.  
  9218.   405   ERROR_VIO_NO_POPUP
  9219.           Pop-up window not allocated.
  9220.  
  9221.   406   ERROR_VIO_EXISTING_POPUP
  9222.           Pop-up window on screen (NoWait).
  9223.  
  9224.   407   ERROR_KBD_SMG_ONLY
  9225.           Valid from session manager only.
  9226.  
  9227.   408   ERROR_KBD_INVALID_ASCIIZ
  9228.           Invalid ASCIIZ length.
  9229.  
  9230.   409   ERROR_KBD_INVALID_MASK
  9231.           Invalid replacement mask.
  9232.  
  9233.   410   ERROR_KBD_REGISTER
  9234.           KbdRegister not allowed.
  9235.  
  9236.   411   ERROR_KBD_DEREGISTER
  9237.           KbdDeRegister not allowed.
  9238.  
  9239.   412   ERROR_MOUSE_SMG_ONLY
  9240.           Valid from session manager only.
  9241.  
  9242.   413   ERROR_MOUSE_INVALID_ASCIIZ
  9243.           Invalid ASCIIZ length.
  9244.  
  9245.   414   ERROR_MOUSE_INVALID_MASK
  9246.           Invalid replacement mask.
  9247.  
  9248.   415   ERROR_MOUSE_REGISTER
  9249.           Mouse register not allowed.
  9250.  
  9251.   416   ERROR_MOUSE_DEREGISTER
  9252.           Mouse deregister not allowed.
  9253.  
  9254.   417   ERROR_SMG_BAD_ACTION
  9255.           Invalid action specified.
  9256.  
  9257.   418   ERROR_SMG_INVALID_CALL
  9258.           INIT called more than once, or invalid session identity.
  9259.  
  9260.   419   ERROR_SCS_SG_NOTFOUND
  9261.           New session number.
  9262.  
  9263.   420   ERROR_SCS_NOT_SHELL
  9264.           Caller is not shell.
  9265.  
  9266.   421   ERROR_VIO_INVALID_PARMS
  9267.           Invalid parameters passed.
  9268.  
  9269.   422   ERROR_VIO_FUNCTION_OWNED
  9270.           Save/restore already owned.
  9271.  
  9272.   423   ERROR_VIO_RETURN
  9273.           Non-destruct return (undo).
  9274.  
  9275.   424   ERROR_SCS_INVALID_FUNCTION
  9276.           Caller invalid function.
  9277.  
  9278.   425   ERROR_SCS_NOT_SESSION_MGR
  9279.           Caller not session manager.
  9280.  
  9281.   426   ERROR_VIO_REGISTER
  9282.           Vio register not allowed.
  9283.  
  9284.   427   ERROR_VIO_NO_MODE_THREAD
  9285.           No mode restore thread in SG.
  9286.  
  9287.   428   ERROR_VIO_NO_SAVE_RESTORE_THD
  9288.           No save/restore thread in SG.
  9289.  
  9290.   429   ERROR_VIO_IN_BG
  9291.           Function invalid in background.
  9292.  
  9293.   430   ERROR_VIO_ILLEGAL_DURING_POPUP
  9294.           Function not allowed during pop-up window.
  9295.  
  9296.   431   ERROR_SMG_NOT_BASESHELL
  9297.           Caller is not the base shell.
  9298.  
  9299.   432   ERROR_SMG_BAD_STATUSREQ
  9300.           Invalid status requested.
  9301.  
  9302.   433   ERROR_QUE_INVALID_WAIT
  9303.           NoWait parameter out of bounds.
  9304.  
  9305.   434   ERROR_VIO_LOCK
  9306.           Error returned from Scroll Lock.
  9307.  
  9308.   435   ERROR_MOUSE_INVALID_IOWAIT
  9309.           Invalid parameters for IOWait.
  9310.  
  9311.   436   ERROR_VIO_INVALID_HANDLE
  9312.           Invalid VIO handle.
  9313.  
  9314.   437   ERROR_VIO_ILLEGAL_DURING_LOCK
  9315.           Function not allowed during screen lock.
  9316.  
  9317.   438   ERROR_VIO_INVALID_LENGTH
  9318.           Invalid VIO length.
  9319.  
  9320.   439   ERROR_KBD_INVALID_HANDLE
  9321.           Invalid KBD handle.
  9322.  
  9323.   440   ERROR_KBD_NO_MORE_HANDLE
  9324.           Ran out of handles.
  9325.  
  9326.   441   ERROR_KBD_CANNOT_CREATE_KCB
  9327.           Unable to create kcb.
  9328.  
  9329.   442   ERROR_KBD_CODEPAGE_LOAD_INCOMPL
  9330.           Unsuccessful code-page load.
  9331.  
  9332.   443   ERROR_KBD_INVALID_CODEPAGE_ID
  9333.           Invalid code-page identity.
  9334.  
  9335.   444   ERROR_KBD_NO_CODEPAGE_SUPPORT
  9336.           No code page support.
  9337.  
  9338.   445   ERROR_KBD_FOCUS_REQUIRED
  9339.           Keyboard focus required.
  9340.  
  9341.   446   ERROR_KBD_FOCUS_ALREADY_ACTIVE
  9342.           Calling thread has an outstanding focus.
  9343.  
  9344.   447   ERROR_KBD_KEYBOARD_BUSY
  9345.           Keyboard is busy.
  9346.  
  9347.   448   ERROR_KBD_INVALID_CODEPAGE
  9348.           Invalid code page.
  9349.  
  9350.   449   ERROR_KBD_UNABLE_TO_FOCUS
  9351.           Focus attempt failed.
  9352.  
  9353.   450   ERROR_SMG_SESSION_NON_SELECT
  9354.           Session is not selectable.
  9355.  
  9356.   451   ERROR_SMG_SESSION_NOT_FOREGRND
  9357.           Parent/child session is not foreground.
  9358.  
  9359.   452   ERROR_SMG_SESSION_NOT_PARENT
  9360.           Not parent of requested child.
  9361.  
  9362.   453   ERROR_SMG_INVALID_START_MODE
  9363.           Invalid session start mode.
  9364.  
  9365.   454   ERROR_SMG_INVALID_RELATED_OPT
  9366.           Invalid session start related option.
  9367.  
  9368.   455   ERROR_SMG_INVALID_BOND_OPTION
  9369.           Invalid session bond option.
  9370.  
  9371.   456   ERROR_SMG_INVALID_SELECT_OPT
  9372.           Invalid session select option.
  9373.  
  9374.   457   ERROR_SMG_START_IN_BACKGROUND
  9375.           Session started in background.
  9376.  
  9377.   458   ERROR_SMG_INVALID_STOP_OPTION
  9378.           Invalid session stop option.
  9379.  
  9380.   459   ERROR_SMG_BAD_RESERVE
  9381.           Reserved parameters are not zero.
  9382.  
  9383.   460   ERROR_SMG_PROCESS_NOT_PARENT
  9384.           Session parent process already exists.
  9385.  
  9386.   461   ERROR_SMG_INVALID_DATA_LENGTH
  9387.           Invalid data length.
  9388.  
  9389.   462   ERROR_SMG_NOT_BOUND
  9390.           Parent is not bound.
  9391.  
  9392.   463   ERROR_SMG_RETRY_SUB_ALLOC
  9393.           Retry request block allocation.
  9394.  
  9395.   464   ERROR_KBD_DETACHED
  9396.           This call is not allowed for a detached PID.
  9397.  
  9398.   465   ERROR_VIO_DETACHED
  9399.           This call is not allowed for a detached PID.
  9400.  
  9401.   466   ERROR_MOU_DETACHED
  9402.           This call is not allowed for a detached PID.
  9403.  
  9404.   467   ERROR_VIO_FONT
  9405.           No font is available to support the mode.
  9406.  
  9407.   468   ERROR_VIO_USER_FONT
  9408.           User font is active.
  9409.  
  9410.   469   ERROR_VIO_BAD_CP
  9411.           Invalid code page specified.
  9412.  
  9413.   470   ERROR_VIO_NO_CP
  9414.           System displays do not support code page.
  9415.  
  9416.   471   ERROR_VIO_NA_CP
  9417.           Current display does not support code page.
  9418.  
  9419.   472   ERROR_INVALID_CODE_PAGE
  9420.           Invalid code page.
  9421.  
  9422.   473   ERROR_CPLIST_TOO_SMALL
  9423.           Code page list is too small.
  9424.  
  9425.   474   ERROR_CP_NOT_MOVED
  9426.           Code page was not moved.
  9427.  
  9428.   475   ERROR_MODE_SWITCH_INIT
  9429.           Mode switch initialization error.
  9430.  
  9431.   476   ERROR_CODE_PAGE_NOT_FOUND
  9432.           Code page was not found.
  9433.  
  9434.   477   ERROR_UNEXPECTED_SLOT_RETURNED
  9435.           Internal error.
  9436.  
  9437.   478   ERROR_SMG_INVALID_TRACE_OPTION
  9438.           Invalid start session trace indicator.
  9439.  
  9440.   479   ERROR_VIO_INTERNAL_RESOURCE
  9441.           VIO internal resource error.
  9442.  
  9443.   480   ERROR_VIO_SHELL_INIT
  9444.           VIO shell initialization error.
  9445.  
  9446.   481   ERROR_SMG_NO_HARD_ERRORS
  9447.           No session manager hard errors.
  9448.  
  9449.   482   ERROR_CP_SWITCH_INCOMPLETE
  9450.           DosSetProcessCp is unable to set a KBD or VIO code page.
  9451.  
  9452.   483   ERROR_VIO_TRANSPARENT_POPUP
  9453.           Error during VIO pop-up window.
  9454.  
  9455.   484   ERROR_CRITSEC_OVERFLOW
  9456.           Critical section overflow.
  9457.  
  9458.   485   ERROR_CRITSEC_UNDERFLOW
  9459.           Critical section underflow.
  9460.  
  9461.   486   ERROR_VIO_BAD_RESERVE
  9462.           Reserved parameter is not zero.
  9463.  
  9464.   487   ERROR_INVALID_ADDRESS
  9465.           Invalid physical address.
  9466.  
  9467.   488   ERROR_ZERO_SELECTORS_REQUESTED
  9468.           At least one selector must be requested.
  9469.  
  9470.   489   ERROR_NOT_ENOUGH_SELECTORS_AVA
  9471.           Not enough GDT selectors to satisfy request.
  9472.  
  9473.   490   ERROR_INVALID_SELECTOR
  9474.           Not a GDT selector.
  9475.  
  9476.   491   ERROR_SMG_INVALID_PROGRAM_TYPE
  9477.           Invalid program type.
  9478.  
  9479.   492   ERROR_SMG_INVALID_PGM_CONTROL
  9480.           Invalid program control.
  9481.  
  9482.   493   ERROR_SMG_INVALID_INHERIT_OPT
  9483.           Invalid inherit option.
  9484.  
  9485.   494   ERROR_VIO_EXTENDED_SG
  9486.  
  9487.  
  9488.   495   ERROR_VIO_NOT_PRES_MGR_SG
  9489.  
  9490.  
  9491.   496   ERROR_VIO_SHIELD_OWNED
  9492.  
  9493.  
  9494.   497   ERROR_VIO_NO_MORE_HANDLES
  9495.  
  9496.  
  9497.   498   ERROR_VIO_SEE_ERROR_LOG
  9498.  
  9499.  
  9500.   499   ERROR_VIO_ASSOCIATED_DC
  9501.  
  9502.  
  9503.   500   ERROR_KBD_NO_CONSOLE
  9504.  
  9505.  
  9506.   501   ERROR_MOUSE_NO_CONSOLE
  9507.  
  9508.  
  9509.   502   ERROR_MOUSE_INVALID_HANDLE
  9510.  
  9511.  
  9512.   503   ERROR_SMG_INVALID_DEBUG_PARMS
  9513.  
  9514.  
  9515.   504   ERROR_KBD_EXTENDED_SG
  9516.  
  9517.  
  9518.   505   ERROR_MOU_EXTENDED_SG
  9519.  
  9520.  
  9521.   506   ERROR_SMG_INVALID_ICON_FILE
  9522.  
  9523.  
  9524.   507   ERROR_TRC_PID_NON_EXISTENT
  9525.  
  9526.  
  9527.   508   ERROR_TRC_COUNT_ACTIVE
  9528.  
  9529.  
  9530.   509   ERROR_TRC_SUSPENDED_BY_COUNT
  9531.  
  9532.  
  9533.   510   ERROR_TRC_COUNT_INACTIVE
  9534.  
  9535.  
  9536.   511   ERROR_TRC_COUNT_REACHED
  9537.  
  9538.  
  9539.   512   ERROR_NO_MC_TRACE
  9540.  
  9541.  
  9542.   513   ERROR_MC_TRACE
  9543.  
  9544.  
  9545.   514   ERROR_TRC_COUNT_ZERO
  9546.  
  9547.  
  9548.   515   ERROR_SMG_TOO_MANY_DDS
  9549.  
  9550.  
  9551.   516   ERROR_SMG_INVALID_NOTIFICATION
  9552.  
  9553.  
  9554.   517   ERROR_LF_INVALID_FUNCTION
  9555.  
  9556.  
  9557.   518   ERROR_LF_NOT_AVAIL
  9558.  
  9559.  
  9560.   519   ERROR_LF_SUSPENDED
  9561.  
  9562.  
  9563.   520   ERROR_LF_BUF_TOO_SMALL
  9564.  
  9565.  
  9566.   521   ERROR_LF_BUFFER_CORRUPTED
  9567.  
  9568.  
  9569.   521   ERROR_LF_BUFFER_FULL
  9570.  
  9571.  
  9572.   522   ERROR_LF_INVALID_DAEMON
  9573.  
  9574.  
  9575.   522   ERROR_LF_INVALID_RECORD
  9576.  
  9577.  
  9578.   523   ERROR_LF_INVALID_TEMPL
  9579.  
  9580.  
  9581.   523   ERROR_LF_INVALID_SERVICE
  9582.  
  9583.  
  9584.   524   ERROR_LF_GENERAL_FAILURE
  9585.  
  9586.  
  9587.   525   ERROR_LF_INVALID_ID
  9588.  
  9589.  
  9590.   526   ERROR_LF_INVALID_HANDLE
  9591.  
  9592.  
  9593.   527   ERROR_LF_NO_ID_AVAIL
  9594.  
  9595.  
  9596.   528   ERROR_LF_TEMPLATE_AREA_FULL
  9597.  
  9598.  
  9599.   529   ERROR_LF_ID_IN_USE
  9600.  
  9601.  
  9602.   530   ERROR_MOU_NOT_INITIALIZED
  9603.  
  9604.  
  9605.   531   ERROR_MOUINITREAL_DONE
  9606.  
  9607.  
  9608.   532   ERROR_DOSSUB_CORRUPTED
  9609.  
  9610.  
  9611.   533   ERROR_MOUSE_CALLER_NOT_SUBSYS
  9612.  
  9613.  
  9614.   534   ERROR_ARITHMETIC_OVERFLOW
  9615.  
  9616.  
  9617.   535   ERROR_TMR_NO_DEVICE
  9618.  
  9619.  
  9620.   536   ERROR_TMR_INVALID_TIME
  9621.  
  9622.  
  9623.   537   ERROR_PVW_INVALID_ENTITY
  9624.  
  9625.  
  9626.   538   ERROR_PVW_INVALID_ENTITY_TYPE
  9627.  
  9628.  
  9629.   539   ERROR_PVW_INVALID_SPEC
  9630.  
  9631.  
  9632.   540   ERROR_PVW_INVALID_RANGE_TYPE
  9633.  
  9634.  
  9635.   541   ERROR_PVW_INVALID_COUNTER_BLK
  9636.  
  9637.  
  9638.   542   ERROR_PVW_INVALID_TEXT_BLK
  9639.  
  9640.  
  9641.   543   ERROR_PRF_NOT_INITIALIZED
  9642.  
  9643.  
  9644.   544   ERROR_PRF_ALREADY_INITIALIZED
  9645.  
  9646.  
  9647.   545   ERROR_PRF_NOT_STARTED
  9648.  
  9649.  
  9650.   546   ERROR_PRF_ALREADY_STARTED
  9651.  
  9652.  
  9653.   547   ERROR_PRF_TIMER_OUT_OF_RANGE
  9654.  
  9655.  
  9656.   548   ERROR_PRF_TIMER_RESET
  9657.  
  9658.  
  9659.   639   ERROR_VDD_LOCK_USEAGE_DENIED
  9660.  
  9661.  
  9662.   640   ERROR_TIMEOUT
  9663.  
  9664.  
  9665.   641   ERROR_VDM_DOWN
  9666.  
  9667.  
  9668.   642   ERROR_VDM_LIMIT
  9669.  
  9670.  
  9671.   643   ERROR_VDD_NOT_FOUND
  9672.  
  9673.  
  9674.   644   ERROR_INVALID_CALLER
  9675.  
  9676.  
  9677.   645   ERROR_PID_MISMATCH
  9678.  
  9679.  
  9680.   646   ERROR_INVALID_VDD_HANDLE
  9681.  
  9682.  
  9683.   647   ERROR_VLPT_NO_SPOOLER
  9684.  
  9685.  
  9686.   648   ERROR_VCOM_DEVICE_BUSY
  9687.  
  9688.  
  9689.   649   ERROR_VLPT_DEVICE_BUSY
  9690.  
  9691.  
  9692.   650   ERROR_NESTING_TOO_DEEP
  9693.  
  9694.  
  9695.   651   ERROR_VDD_MISSING
  9696.  
  9697.  
  9698.   691   ERROR_IMP_INVALID_PARM
  9699.  
  9700.  
  9701.   692   ERROR_IMP_INVALID_LENGTH
  9702.  
  9703.  
  9704.   693   MSG_HPFS_DISK_ERROR_WARN
  9705.  
  9706.  
  9707.   730   ERROR_MON_BAD_BUFFER
  9708.  
  9709.  
  9710.   731   ERROR_MODULE_CORRUPTED
  9711.  
  9712.  
  9713.   2055   ERROR_LF_TIMEOUT
  9714.  
  9715.  
  9716.   2057   ERROR_LF_SUSPEND_SUCCESS
  9717.  
  9718.  
  9719.   2058   ERROR_LF_RESUME_SUCCESS
  9720.  
  9721.  
  9722.   2059   ERROR_LF_REDIRECT_SUCCESS
  9723.  
  9724.  
  9725.   2060   ERROR_LF_REDIRECT_FAILURE
  9726.  
  9727.  
  9728.   32768   ERROR_SWAPPER_NOT_ACTIVE
  9729.  
  9730.  
  9731.   32769   ERROR_INVALID_SWAPID
  9732.  
  9733.  
  9734.   32770   ERROR_IOERR_SWAP_FILE
  9735.  
  9736.  
  9737.   32771   ERROR_SWAP_TABLE_FULL
  9738.  
  9739.  
  9740.   32772   ERROR_SWAP_FILE_FULL
  9741.  
  9742.  
  9743.   32773   ERROR_CANT_INIT_SWAPPER
  9744.  
  9745.  
  9746.   32774   ERROR_SWAPPER_ALREADY_INIT
  9747.  
  9748.  
  9749.   32775   ERROR_PMM_INSUFFICIENT_MEMORY
  9750.  
  9751.  
  9752.   32776   ERROR_PMM_INVALID_FLAGS
  9753.  
  9754.  
  9755.   32777   ERROR_PMM_INVALID_ADDRESS
  9756.  
  9757.  
  9758.   32778   ERROR_PMM_LOCK_FAILED
  9759.  
  9760.  
  9761.   32779   ERROR_PMM_UNLOCK_FAILED
  9762.  
  9763.  
  9764.   32780   ERROR_PMM_MOVE_INCOMPLETE
  9765.  
  9766.  
  9767.   32781   ERROR_UCOM_DRIVE_RENAMED
  9768.  
  9769.  
  9770.   32782   ERROR_UCOM_FILENAME_TRUNCATED
  9771.  
  9772.  
  9773.   32783   ERROR_UCOM_BUFFER_LENGTH
  9774.  
  9775.  
  9776.   32784   ERROR_MON_CHAIN_HANDLE
  9777.  
  9778.  
  9779.   32785   ERROR_MON_NOT_REGISTERED
  9780.  
  9781.  
  9782.   32786   ERROR_SMG_ALREADY_TOP
  9783.  
  9784.  
  9785.   32787   ERROR_PMM_ARENA_MODIFIED
  9786.  
  9787.  
  9788.   32788   ERROR_SMG_PRINTER_OPEN
  9789.  
  9790.  
  9791.   32789   ERROR_PMM_SET_FLAGS_FAILED
  9792.  
  9793.  
  9794.   32790   ERROR_INVALID_DOS_DD
  9795.  
  9796.  
  9797.   32791   ERROR_BLOCKED
  9798.  
  9799.  
  9800.   32792   ERROR_NOBLOCK
  9801.  
  9802.  
  9803.   32793   ERROR_INSTANCE_SHARED
  9804.  
  9805.  
  9806.   32794   ERROR_NO_OBJECT
  9807.  
  9808.  
  9809.   32795   ERROR_PARTIAL_ATTACH
  9810.  
  9811.  
  9812.   32796   ERROR_INCACHE
  9813.  
  9814.  
  9815.   32797   ERROR_SWAP_IO_PROBLEMS
  9816.  
  9817.  
  9818.   32798   ERROR_CROSSES_OBJECT_BOUNDARY
  9819.  
  9820.  
  9821.   32799   ERROR_LONGLOCK
  9822.  
  9823.  
  9824.   32800   ERROR_SHORTLOCK
  9825.  
  9826.  
  9827.   32801   ERROR_UVIRTLOCK
  9828.  
  9829.  
  9830.   32802   ERROR_ALIASLOCK
  9831.  
  9832.  
  9833.   32803   ERROR_ALIAS
  9834.  
  9835.  
  9836.   32804   ERROR_NO_MORE_HANDLES
  9837.  
  9838.  
  9839.   32805   ERROR_SCAN_TERMINATED
  9840.  
  9841.  
  9842.   32806   ERROR_TERMINATOR_NOT_FOUND
  9843.  
  9844.  
  9845.   32807   ERROR_NOT_DIRECT_CHILD
  9846.  
  9847.  
  9848.   32808   ERROR_DELAY_FREE
  9849.  
  9850.  
  9851.   32809   ERROR_GUARDPAGE
  9852.  
  9853.  
  9854.   32900   ERROR_SWAPERROR
  9855.  
  9856.  
  9857.   32901   ERROR_LDRERROR
  9858.  
  9859.  
  9860.   32902   ERROR_NOMEMORY
  9861.  
  9862.  
  9863.   32903   ERROR_NOACCESS
  9864.  
  9865.  
  9866.   32904   ERROR_NO_DLL_TERM
  9867.  
  9868.  
  9869.   65026   ERROR_CPSIO_CODE_PAGE_INVALID
  9870.  
  9871.  
  9872.   65027   ERROR_CPSIO_NO_SPOOLER
  9873.  
  9874.  
  9875.   65028   ERROR_CPSIO_FONT_ID_INVALID
  9876.  
  9877.  
  9878.   65033   ERROR_CPSIO_INTERNAL_ERROR
  9879.  
  9880.  
  9881.   65034   ERROR_CPSIO_INVALID_PTR_NAME
  9882.  
  9883.  
  9884.   65037   ERROR_CPSIO_NOT_ACTIVE
  9885.  
  9886.  
  9887.   65039   ERROR_CPSIO_PID_FULL
  9888.  
  9889.  
  9890.   65040   ERROR_CPSIO_PID_NOT_FOUND
  9891.  
  9892.  
  9893.   65043   ERROR_CPSIO_READ_CTL_SEQ
  9894.  
  9895.  
  9896.   65045   ERROR_CPSIO_READ_FNT_DEF
  9897.  
  9898.  
  9899.   65047   ERROR_CPSIO_WRITE_ERROR
  9900.  
  9901.  
  9902.   65048   ERROR_CPSIO_WRITE_FULL_ERROR
  9903.  
  9904.  
  9905.   65049   ERROR_CPSIO_WRITE_HANDLE_BAD
  9906.  
  9907.  
  9908.   65074   ERROR_CPSIO_SWIT_LOAD
  9909.  
  9910.  
  9911.   65077   ERROR_CPSIO_INV_COMMAND
  9912.  
  9913.  
  9914.   65078   ERROR_CPSIO_NO_FONT_SWIT
  9915.  
  9916.  
  9917.   65079   ERROR_ENTRY_IS_CALLGATE
  9918.  
  9919.  
  9920. ΓòÉΓòÉΓòÉ 13. Specifications ΓòÉΓòÉΓòÉ
  9921.  
  9922. Specifications covered: 
  9923.  
  9924. Γûá API Calls Made 
  9925.  
  9926. Γûá Memory Usage 
  9927.  
  9928. Γûá IX3 File Format 
  9929.  
  9930. Γûá DBF File Format 
  9931.  
  9932. Γûá DBT File Format 
  9933.  
  9934. Γûá Custom Sort-Compare Function 
  9935.  
  9936. Γûá Custom Build-Key 
  9937.  
  9938. Γûá Custom Expression Parser 
  9939.  
  9940.  
  9941. ΓòÉΓòÉΓòÉ 13.1. OS/2 API Calls Made ΓòÉΓòÉΓòÉ
  9942.  
  9943. The following are the API calls made by Bullet. 
  9944.  
  9945.  DosAllocMem             DosClose                 DosCopy 
  9946.  DosCloseMutexSem        DosCreateDir             DosCreateMutexSem 
  9947.  DosDelete (*)           DosErrClass              DosExitList 
  9948.  DosForceDelete          DosFreeMem               DosGetDateTime 
  9949.  DosMapCase              DosOpen                  DosQueryCollate 
  9950.  DosQueryCp              DosQueryCtryInfo         DosQueryCurrentDisk 
  9951.  DosQueryFSAttach        DosQueryHType            DosQuerySysInfo 
  9952.  DosMove                 DosRead                  DosReleaseMutexSem 
  9953.  DosRequestMutexSem      DosResetBuffer           DosScanEnv 
  9954.  DosSetFileLocks         DosSetFilePtr            DosSetFileSize 
  9955.  DosSetMaxFH             DosSetRelMaxFH           DosWrite 
  9956.  
  9957.  (*) DosForceDelete is used in favor of DosDelete. 
  9958.  
  9959.  
  9960. ΓòÉΓòÉΓòÉ 13.2. Bullet Memory Usage ΓòÉΓòÉΓòÉ
  9961.  
  9962. Memory is committed when allocated, using the PAG_COMMIT and the PAG_WRITE 
  9963. flags.  This is memory allocated by Bullet itself.  Additional memory needs are 
  9964. made by your code, such as parameter pack data, key buffers, and data record 
  9965. buffers. 
  9966.  
  9967. Code 
  9968.  
  9969. Bullet uses 7 pages for code, or less than 28KB. 
  9970.  
  9971. Data 
  9972.  
  9973. Γûá  Shared Data 
  9974.  
  9975. A single page of shared memory is used by all Bullet processes. 
  9976.  
  9977. Γûá  Instance Data 
  9978.  
  9979. One page of private memory is used by each Bullet processes. 
  9980.  
  9981. Γûá  Handle Data 
  9982.  
  9983. One page of private memory is used by each open Bullet index file.  For open 
  9984. data files, one page of private memory is used for files with 121 or fewer 
  9985. fields.  Two pages are used for files with 249 or fewer fields. Three pages are 
  9986. used for files with 250 or more fields. 
  9987.  
  9988. For example, if one machine is running 2 Bullet processes, each with 10 open 
  9989. data files with 12 fields each, and 10 index files (one for each data file), 
  9990. its total memory usage is: 
  9991.  
  9992.      Total code is 28KB. 
  9993.      Shared data is 4KB. 
  9994.      Instance data is 2 processes * 4KB, or 8KB (plus INIT_XB use shown 
  9995.       below). 
  9996.      DBF file data is 2 * 10 files * 4KB, or 80KB. 
  9997.      Index file data is 2 * 10 files * 4KB, or 80KB. 
  9998.  
  9999.  Total memory committed by Bullet for the above is 200KB, plus code and data of 
  10000.  your two applications (or your single application, if the same application is 
  10001.  being run twice).  With no files open, for example when starting your program, 
  10002.  only 40KB is committed.  Thereafter, 4KB per open file.  The memory is freed 
  10003.  when the file is closed. 
  10004.  
  10005.  Γûá  Temporary Data 
  10006.  
  10007.  Additional memory is allocated on a temporary basis, where the allocation is 
  10008.  requested on entry to, and is freed upon exiting from, the routine called. 
  10009.  INIT_XB's allocation can be considered permanent since INIT_XB is usually not 
  10010.  exited until the program has ended.  The following are the routines and the 
  10011.  single requested amount: 
  10012.  
  10013.      Routine          Memory Allocated, in KB
  10014.  
  10015.   INIT_XB             8 for 1024 MAX_FILES version; 4KB for 100 and 250 MAX_FILES versions
  10016.   BACKUP_FILE_XB      8
  10017.   CREATE_DATA_XB      4 for 1-121 fields, 8 for 122-249 fields, 12 for 250+ fields
  10018.   CREATE_INDEX_XB     4
  10019.   PACK_RECORDS_XB     adjustable, 128 default (less if file is smaller)
  10020.   REINDEX_XB          adjustable, 144 default (minimum size is 48KB)
  10021.   UPDATE_XB           varies:      40 + sum of record lengths where AP[].recNo!=0
  10022.  
  10023.  Γûá  Stack Data 
  10024.  
  10025.  Stack requirements are 8KB minimum for Bullet.  No single stack allocation 
  10026.  requests more than 4KB at a time (ie all changes to ESP (the CPU stack 
  10027.  pointer) are less than 4KB at any one time), but some routines nest and 
  10028.  require up to the minimum 8KB in total.  The minimum recommended stack size 
  10029.  for your Bullet application is 16KB.  It's likely that you need to use a much 
  10030.  larger size for your main program's stack use.  If you have any doubt about 
  10031.  stack space, double it, twice even. 
  10032.  
  10033.  
  10034. ΓòÉΓòÉΓòÉ 13.3. IX3 File Format ΓòÉΓòÉΓòÉ
  10035.  
  10036. The IX3 index file is composed of a header followed by node data.  The header 
  10037. layout is detailed below, followed by the node format. 
  10038.  
  10039. Index Header 
  10040.  
  10041. // nnn, where nnn is the offset of that item relative to the start of the file
  10042.  
  10043. CHAR fileID[4];     // 000 file id = '31ch'
  10044. ULONG nodeSize;     // 004 size of a node, in bytes
  10045. ULONG rootNode;     // 008 root node (1-based)
  10046. ULONG noKeys;       // 012 total number of keys
  10047. ULONG availNode;    // 016 next available node (link to, 0 if none, 1-based)
  10048. ULONG freeNode;     // 020 next free node
  10049. ULONG keyLength;    // 024 length of key
  10050. ULONG maxKeys;      // 028 maximum number of keys on a node
  10051. ULONG codePage;     // 032 code page from CreateIndexFile
  10052. ULONG countryCode;  // 036 country code from CreateIndexFile
  10053. ULONG sortFunction; // 040 system (1-9) or custom (10-19)
  10054.                     //     high word has flags: bit0=1 dups allowed
  10055.                     //                          bit1-15 rez
  10056.  
  10057. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10058. // More details on this is in the Custom Expression Parser Specifications.
  10059. // For each key part in KH.expression a 4-byte structure is used in XLATEX:
  10060.  
  10061. typedef struct _XLATEX {
  10062.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10063.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10064.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10065. } XLATEX;
  10066.  
  10067. ULONG xlateCount;         // 044 number of key fields (64/4=16 max fields)
  10068. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10069. CHAR  miscWorkspace[236]; // 112-347 B-tree workspace
  10070. CHAR  expression[160];    // 348 key expression, user (0-Terminated)
  10071. ULONG CTsize;             // 508 size of collate table following
  10072. CHAR  collateTable[256];  // 512 collate table, fill at CreateIndexXB
  10073. CHAR  rez[256];           // 768 to 1023 reserved (header size=1024 bytes)
  10074.  
  10075. Node Data 
  10076.  
  10077. Directly after the header the node data starts.  Each node is either 512, 1024, 
  10078. or 2048 bytes long.  Each node contains a key count, indicating the number of 
  10079. active keys on the node, followed by key data. 
  10080.  
  10081. // nnn, where nnn is the offset of that item relative to the start of the node
  10082.  
  10083. CHAR  keyCount;         // 000 1 to maxKeys (in header above)
  10084. ULONG backNode;         // 001 previous node page, or 0 if this node is a leaf
  10085. XNODE node[maxKeys];    // 005...
  10086.  
  10087. For each key on the node: 
  10088.  
  10089. typedef struct _XNODE {
  10090. CHAR  keyValue[keyLength]; // 005   actual key   (keyLength from header)
  10091. ULONG recordNo;            // 005+keyLength   record number for key
  10092. ULONG fwdNode;             // 005+keyLength+4   next node page, or 0 if leaf
  10093. } XNODE;
  10094.  
  10095. backNode and fwdNode are node numbers.  The first node is 1, and is located 
  10096. directly after the header.  The last node used is at header:freeNode-1.  Each 
  10097. fwdNode of a key is also the next key's backNode.  If the node has had all keys 
  10098. removed, its node number is placed on the top of the header:availNode list, and 
  10099. the first 4 bytes of the node are used as a link to the previous list top. 
  10100.  
  10101.  
  10102. ΓòÉΓòÉΓòÉ 13.4. DBF File Format ΓòÉΓòÉΓòÉ
  10103.  
  10104. The DBF data file is composed of a header, field descriptors, one per field, 
  10105. and the actual record data.  The header layout is detailed below, followed by 
  10106. the field descriptor layout and then the description of the data record. 
  10107.  
  10108. DBF Header 
  10109.  
  10110. // nnn, where nnn is the offset of that item relative to the start of the file
  10111.  
  10112. CHAR  fileID;           // 000 file id byte
  10113. CHAR  lastUpdateYR;     // 001 binary year-1900
  10114. CHAR  lastUpdateMO;     // 002 binary month (1-12)
  10115. CHAR  lastUpdateDA;     // 003 binary day (1-31)
  10116. ULONG noRecords;        // 004 total number of records
  10117. SHORT headerLength;     // 008 length of data header
  10118. SHORT recordLength;     // 010 record length
  10119. SHORT nada;             // 012 reserved
  10120. CHAR  xactionFlag;      // 014 flag indicating incomplete dBASE transaction (n/a)
  10121. CHAR  encryptFlag;      // 015 flag indicating encrypted (n/a)
  10122. CHAR  filler[16];       // 016 fill to 32 bytes
  10123.  
  10124. Field Descriptors 
  10125.  
  10126. For each field, a descriptor is stored in the DBF.  The first descriptor starts 
  10127. directly after the header, at file offset 32 (the 33rd byte).  Each descriptor 
  10128. is 32 bytes.  After the last descriptor, a byte with ASCII value 13 (0x0D) is 
  10129. stored.  Following this byte, the record data starts. 
  10130.  
  10131. // nnn, where nnn is offset of item relative to the start of the descriptor
  10132.  
  10133. CHAR  fieldName[11];    // 000 ASCII, UPPER, underscore, zero-filled, (0T)
  10134. CHAR  fieldType;        // 011 UPPER C,N,D,L,M
  10135. ULONG fieldDA;          // 012 not used
  10136. CHAR  fieldLength;      // 016 1-255 bytes, depending on fieldType
  10137. CHAR  fieldDC;          // 017 places right of decimal point
  10138. SHORT altFieldLength;   // 018 alternate field length when fieldLength==0
  10139. CHAR  filler[12];       // 020 not used
  10140.  
  10141. // altFieldLength is proprietary to Bullet, and can be used if Xbase
  10142. // compatibility is not required and fields need to be larger than 255 bytes.
  10143. // To use it, set fieldLength=0 and altFieldLength to > 255 bytes.
  10144.  
  10145. Record Data 
  10146.  
  10147. The DBF data are free-form, fixed-length records.  Each data record starts with 
  10148. a one-byte 'tag' field, which is implicitly defined for all records (hence, it 
  10149. is not a formal field and has no descriptor).  Following the tag field is the 
  10150. first field of the record, and following that field (whose length is described 
  10151. in the field's descriptor) is the next field, and so on.  No separators are 
  10152. used between fields.  After the very last data record in the file, DBF 
  10153. specification dictates that an end of file marker be placed, so at the end of 
  10154. the file is a byte of value ASCII 26 (0x1A). 
  10155.  
  10156. Record layout is as you define in your application.  It must match the layout
  10157. as described in the field descriptors, byte-for-byte.
  10158.  
  10159. Increasing DBF Performance 
  10160.  
  10161. Records are stored in the order they were written.  To improve performance, 
  10162. especially indexed-sequential access, the data file may be sorted, or 
  10163. clustered, by reading each record in primary key order, then writing that 
  10164. record to a new DBF data file.  Repeat for each record.  After all records have 
  10165. been written, reindex the newly created DBF data file (and all related index 
  10166. files).  After this, delete the old files (data and index), and rename the new 
  10167. ones to the filenames required.  This technique maximizes cache efficiency, and 
  10168. can easily offer 10x performance increase in access speed. 
  10169.  
  10170.  
  10171. ΓòÉΓòÉΓòÉ 13.5. DBT File Format ΓòÉΓòÉΓòÉ
  10172.  
  10173. The DBT memo file is composed of a header followed by memo data, stored in one 
  10174. or more blocks.  The header layout is detailed below, followed by the memo 
  10175. record. 
  10176.  
  10177. DBT Header 
  10178.  
  10179. // nnn, where nnn is the offset of that item relative to the start of the file
  10180.  
  10181. ULONG memoAvailBlock;   // 000 next available block (header is block 0)
  10182. ULONG memoRez;          // 004 not used
  10183. CHAR  memoFilename[8];  // 008 filename proper (first 8 of filename proper)
  10184. ULONG memoRez2;         // 016 not used (apparently)
  10185. ULONG memoBlockSize;    // 020 block size, must be at least 24
  10186.  
  10187. // the rest of the header block (to block size bytes) is unused
  10188.  
  10189. Memo Record 
  10190.  
  10191. // nnn, where nnn is offset of item relative to the start of the memo record
  10192.  
  10193. ULONG memoAvail;        // 000 next available link
  10194. ULONG memoSize;         // 004 size of data (including this and memoAvail)
  10195. CHAR  memoData;         // 008 for as many bytes as memoSize, less 8
  10196.  
  10197. A memo may use one or more blocks (each block is a fixed size), but allocations 
  10198. are always contiguous.  Unused bytes after the memo data (to the end of the 
  10199. last block allocated to that memo record) are undefined.  memoAvail is 0x8FFFF 
  10200. for all active memo records.  For deleted memo records, memoAvail is used as a 
  10201. link in the memoAvail list.  memoSize is the total bytes used by the memo, 
  10202. including the memoAvail and memoSize data, so it is the size of the real data + 
  10203. 8 bytes. 
  10204.  
  10205.  
  10206. ΓòÉΓòÉΓòÉ 13.6. Custom Sort-Compare Function ΓòÉΓòÉΓòÉ
  10207.  
  10208. Bullet provides 10 custom sort-compare functions, in addition to the 6 
  10209. intrinsic sort-compare functions (ASCII, NLS, and the four integer compares). 
  10210. The custom function you supply is not actually a sort function, as the name 
  10211. implies, but a compare function.  Basically, two strings are supplied and your 
  10212. function determines string1's relation to string2 (<, >, or ==). 
  10213.  
  10214. The strings supplied (via pointers) are not C strings, and they are not 
  10215. (necessarily) 0-terminated.  A count value is passed, indicating the number of 
  10216. bytes to compare.  The handle of the index file for which this compare is being 
  10217. done is also supplied, so that you can interrogate the index file state 
  10218. (STAT_INDEX_XB) for any additional information required. 
  10219.  
  10220. In addition to the compare function this routine performs, a special-case call 
  10221. is made to this routine requesting a pointer to a string of HIGH-VALUES for 
  10222. this sort compare.  The pointer must be to a static memory area that exists for 
  10223. as long as the index file is open, and must be at least as long as count.  This 
  10224. special-case call is indicated by both string pointers==NULL. 
  10225.  
  10226. To use a custom sort-compare function, first use SET_SYSVARS_XB to assign the 
  10227. custom sort ID (10 to 19) with the function's address pointer.  Once assigned, 
  10228. an index file may be created with its CIP.sortFunction set to the sort ID 
  10229. (10-19).  Also, any previously created index file with a custom sort ID may now 
  10230. be opened (but only after you used SET_SYSVARS_XB to assign the sort-compare 
  10231. function pointer).  During the index file create, the sort ID you specified for 
  10232. the create is stored in the index file.  When that index file is later opened, 
  10233. that same sort ID is used, and so requires that the custom sort-compare 
  10234. function already be assigned (with SET_SYSVARS_XB) before opening the index 
  10235. file.  This means that you need to be consistent in your custom sort ID 
  10236. numbering, since each index created forever uses that sort ID you specified. 
  10237.  
  10238. It's simple to create a custom sort-compare function.  The calling convention 
  10239. is APIENTRY (or _System, or __syscall for some compilers), and the parameters 
  10240. are passed to your function on the stack (by Bullet).  A sample prototype for a 
  10241. custom sort-compare function follows: 
  10242.  
  10243. LONG APIENTRY YourCustomSort10(PVOID str1,
  10244.                                PVOID str2,
  10245.                                ULONG count,
  10246.                                ULONG handle);
  10247.  
  10248. If the pointers are not NULL, your routine is to compare str1 to str2, for 
  10249. count bytes, and is to return: 
  10250.  
  10251.         -1 if str1 is less than str2
  10252.          0 if str1 is equal to str2
  10253.          1 if str1 is greater than str2
  10254.  
  10255. str is not a C string, but is of type void.  Cast as required,
  10256. depending on the data expected.
  10257.  
  10258. If str1 and str2 are both NULL, your routine must return a pointer to a static 
  10259. object that contains high-values for the object type.  For example, if the 
  10260. sort-compare is for IEEE floating-point, then the function is to return a 
  10261. pointer to a static data area filled with the highest floating-point value. 
  10262. Depending on your sort-compare routine's functionality, you may need just a 
  10263. single high-value, or multiple high-values, one after the other (e.g., if you 
  10264. are supporting compound key values for binary keys).  The count parameter 
  10265. indicates the total bytes needed, so divide by the object size to get the 
  10266. number of objects required.  Be aware that the object size (in count) is +2 
  10267. bytes for the enumerator if DUPS_ALLOWED was specified when the index file was 
  10268. created.  This high-values object is used in the REINDEX_XB routine, and also 
  10269. the LAST_KEY_XB and GET_LAST_XB routines. 
  10270.  
  10271.  
  10272. ΓòÉΓòÉΓòÉ 13.7. Custom Build-Key ΓòÉΓòÉΓòÉ
  10273.  
  10274. Bullet provides an internal build-key routine that constructs the key from the 
  10275. data record supplied.  The internal routine can be overloaded by your custom 
  10276. build-key routine if you need additional functionality.  It may be used in 
  10277. conjunction with a custom sort-compare function, or an intrinsic Bullet 
  10278. sort-compare. 
  10279.  
  10280. Developing a custom build-key routine requires delving into the internal Bullet 
  10281. data structures.  It is more complicated than a custom sort-compare function, 
  10282. but not really any more complex.  The handle of the index file is passed, and 
  10283. using this, STAT_INDEX_XB is called to get the SIP.herePtr pointer.  This is 
  10284. the pointer to the internal Bullet data structure for this index file.  What 
  10285. needs to be accessed in this structure is the translated key expression.  From 
  10286. this, you have the starting offset in the data record, and the byte count to 
  10287. use, for each key component (up to 16 components per key).  The offset value as 
  10288. stored in the XLATEX structure does not include the tag field byte.  Therefore, 
  10289. to locate to the correct offset, add 1 to the value in offset.  For example, 
  10290. XLATEX.offset=0 means to use the first field, which is the first byte after the 
  10291. tag field byte, but the physical offset, as referenced to recPtr, is not at 
  10292. offset=0, but is at offset=1. 
  10293.  
  10294. This translated key expression structure is: 
  10295.  
  10296. // (This is an excerpt from the IX3 header format)
  10297.  
  10298. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10299. // More details on this is in the Custom Expression Parser Specifications.
  10300. // For each key part in KH.expression a 4-byte structure is used:
  10301.  
  10302. typedef struct _XLATEX {
  10303.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10304.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10305.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10306. } XLATEX;       // (note that offset does not count tag field byte)
  10307.  
  10308. ULONG xlateCount;           // 044 number of key fields (64/4=16 max fields)
  10309. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10310.  
  10311. xlateExpression is at offset +48 relative the IX3 index header.  However, 
  10312. SIP.herePtr points to -384 relative the IX3 index header start.  Therefore, to 
  10313. locate to xlateExpression, you must add 384 to 48.  This means that 
  10314. xlateExpression[0].ftype is located at SIP.herePtr+432.  The number of valid 
  10315. key components in xlateExpression is stored in xlateCount (at SIP.herePtr+428). 
  10316.  
  10317. The calling convention for your custom build-key function is APIENTRY (or 
  10318. _System, or __syscall for some compilers), and the parameters are passed to 
  10319. your function on the stack (by Bullet).  A sample prototype for a build-key 
  10320. function follows: 
  10321.  
  10322. ULONG APIENTRY YourBuildKey(ULONG handle,
  10323.                             PVOID recordPtr,
  10324.                             PVOID keyPtr,
  10325.                             PULONG keyLenPtr
  10326.                             PULONG sortFuncPtr);
  10327.  
  10328. Using the data from xlateExpression, you are to build a key from the data 
  10329. record located at the passed pointer, recordPtr, and are store the built key in 
  10330. the buffer located at keyPtr.  For each key component, you copy from the data 
  10331. record xlateExpression[].length bytes starting at xlateExpression[].offset+1 
  10332. (given the 1-byte tag field which is not accounted for otherwise), and build 
  10333. other key components after previously build parts.  If the index file allows 
  10334. duplicate keys (DUPS_ALLOWED is flagged in SIP.sortFunction), then append an 
  10335. enumerator to the end of the key proper.  The handle of the index file is 
  10336. passed, which is used when calling STAT_INDEX_XB (to get SIP.herePtr).  The 
  10337. return is 0 if successful, or an appropriate Bullet error code (EXB_) should be 
  10338. used.  In addition, the key length is placed in the ULONG data pointed to by 
  10339. keyLenPtr (SIP.keyLength may be used), and the sort-compare function is placed 
  10340. in the ULONG data pointed to by sortFuncPtr (SIP.sortFunction may be used). 
  10341.  
  10342. The routine is also to check if the tag field of the data record matches the 
  10343. skip-tag value, as set by SET_SYSVARS_XB.  If the tag field matches, 
  10344. WRN_SKIP_KEY is to be returned as the 'error' code.  The key is built 
  10345. regardless of a match. 
  10346.  
  10347.  
  10348. ΓòÉΓòÉΓòÉ 13.8. Custom Expression Parser ΓòÉΓòÉΓòÉ
  10349.  
  10350. Bullet provides an internal key expression parser routine that constructs the 
  10351. translated key expression stored in the index file header.  The internal 
  10352. routine can be overloaded by your custom expression parser routine if you need 
  10353. additional functionality.  It may be used in conjunction with a custom 
  10354. sort-compare function, with a custom build-key routine, or with an intrinsic 
  10355. Bullet sort-compare. 
  10356.  
  10357. Developing a custom expression parser routine requires delving into the 
  10358. internal Bullet data structures.  It is more complicated than a custom 
  10359. sort-compare function, and it is also much more complex.  Unlike the custom 
  10360. sort-compare and build-key functions, no handle is passed to the parser.  This 
  10361. is because, rather than using the handle to get the SIP.herePtr, this pointer 
  10362. is passed directly to this routine.  This is the pointer to the internal Bullet 
  10363. data structure for this index file.  What needs to be accessed in this 
  10364. structure is the translated key expression location, as well as the text 
  10365. version of the key expression, as supplied by the programmer/user.  To the 
  10366. XLATEX data you place the starting offset in the data record, and the byte 
  10367. count to use, for each key component you parse from the key expression (up to 
  10368. 16 components per key).  The offset value as stored in the XLATEX structure 
  10369. does not include the tag field byte.  Therefore, the correct offset to store is 
  10370. the physical offset within the record, minus 1.  For example, XLATEX.offset=0 
  10371. should be used for the offset of the first field, which is the first byte after 
  10372. the tag field byte.  For each component parsed, an XLATEX data structure is 
  10373. added to the xlateExpression data area (up to 16).  Unused XLATEX components 
  10374. must be set to 0.  When all components have been stored, the xlateCount value 
  10375. is set to the number of key components stored. 
  10376.  
  10377. DHDptr is the data header pointer.  It is -352 bytes relative the DBF data 
  10378. header.  However, rather than using absolute addressing to locate field 
  10379. descriptor data (needed for parsing), it's recommended that the DBF handle be 
  10380. obtained from the KHptr structure.  Since no file handles are passed, you must 
  10381. read the xbLink handle value from the index file header.  The xbLink handle is 
  10382. stored at KHptr+12.  With this handle, you call the GET_DESCRIPTOR_XB routine 
  10383. to obtain field descriptor info for each field. 
  10384.  
  10385. This translated key expression structure, and text expression location, is at: 
  10386.  
  10387. // (This is an excerpt from the IX3 header format)
  10388.  
  10389. // Translated key expression as done by Parser during CreateIndex and Reindex.
  10390. // For each key part in KH.expression a 4-byte structure is used:
  10391.  
  10392. typedef struct _XLATEX {
  10393.  CHAR  ftype;   // field type (C,N,L, etc.),if bit7=1 and C then do UPPER key
  10394.  CHAR  length;  // bytes to use starting at offset (never > 64)
  10395.  SHORT offset;  // byte offset into data record that length bytes are to be used
  10396. } XLATEX;       // (note that offset does not count tag field byte)
  10397.  
  10398. ULONG xlateCount;           // 044 number of key fields (64/4=16 max fields)
  10399. XLATEX xlateExpression[16]; // 048 key construct info (16 dword's worth)
  10400.       :                     // 112-347   :
  10401. CHAR  expression[160];      // 348 key expression, user (0-Terminated)
  10402.  
  10403. xlateExpression is at offset +48 relative the IX3 index header.  However, 
  10404. KHptr, passed to this routine, points to -384 relative the IX3 index header 
  10405. start.  Therefore, to locate to xlateExpression, you must add 384 to 48.  This 
  10406. means that xlateExpression[0].ftype is located at KHptr+432.  The number of 
  10407. valid key components in xlateExpression is stored in xlateCount (at KHptr+428). 
  10408. To text key expression string, which you are to parse, is located at KHptr+732. 
  10409. This is identical to the expression passed during CREATE_INDEX_XB (and it is 
  10410. CREATE_INDEX_XB that calls this parser routine). 
  10411.  
  10412. The calling convention for your custom key expression parser function is 
  10413. APIENTRY (or _System, or __syscall for some compilers), and the parameters are 
  10414. passed to your function on the stack (by Bullet).  A sample prototype for a 
  10415. build-key function follows: 
  10416.  
  10417. ULONG APIENTRY YourKeyExpressionParser(PVOID DHDptr,
  10418.                                        PVOID KHptr,
  10419.                                        PULONG keyLenPtr);
  10420.  
  10421. You are to parse the text key expression at KHptr+732 and store the key 
  10422. component XLATEX structure values to the XLATEX structure, one for each key 
  10423. component parsed.  In addition, the key length (the sum of the XLATEX.length 
  10424. fields) is placed in the ULONG data pointed to by keyLenPtr.  The keylength may 
  10425. not exceed 64 bytes.  If DUPS_ALLOWED is flagged, add two to the sum of the 
  10426. XLATEX.length fields for the enumerator word. 
  10427.  
  10428. Note:  The key expression has been mapped to upper-case and 0-filled by the 
  10429. time this routine is called. 
  10430.  
  10431. This is probably the most difficult part of customizing Bullet.  However, the 
  10432. difficulty lies not with Bullet, but how you parse.  The idea is simple -- you 
  10433. are to generate a xlateCount value, and for each key component (ie 
  10434. non-contiguous, non-same-type run in the data record), an XLATEX variable 
  10435. describing the method to build that key component out of the data record (type, 
  10436. length, and starting offset) is stored.  The text key expression is available 
  10437. in the index header, and the destination to write to is there, also.  You do 
  10438. need to read the index header at KHptr+12 (ULONG) to obtain the DBF handle for 
  10439. this index file before you can parse the expression.  This because you need to 
  10440. know about the record field names, types, and lengths before you can parse the 
  10441. key expression.  The matter not covered here is that of parsing the expression, 
  10442. which is left to the programmer.  Any lexical parser algorithm may be used, or 
  10443. you may even do no parsing at all, and simply hard-code values into the XLATEX 
  10444. structures. 
  10445.  
  10446. If you've gotten this far, you may find the following data structures useful. 
  10447. The numbers at // nnn are offsets relative the SIP.herePtr and SDP.herePtr 
  10448. pointers.  For example, at SIP.herePtr+352 is a ULONG of the number of key 
  10449. searches requested.  These could be monitored in a separate thread. 
  10450.  
  10451. Relative SIP.herePtr: 
  10452.  
  10453. ULONG fType;            // 000 bit0=0 for index file, btree
  10454. ULONG flags;            // 004 bit0=1 is dirty
  10455.                         //     bit1=1 full lock (count stored in KH.lockCount)
  10456.                         //     bit2=1 shared lock (if bit1=1)
  10457.                         //     bit3-14 reserved (=0)
  10458.                         //     bit15=1 no coalesce on key delete
  10459.                         // 006 BYTE, progress of reindex (0,1-99)
  10460.                         // 007 BYTE
  10461. PVOID morePtr;          // 008 ptr to additional header info, if ever needed
  10462. ULONG xbLink;           // 012 related XB data file handle
  10463. ULONG asMode;           // 016 access-sharing-cache mode of open
  10464. CHAR  filename[260];    // 020 filename at open (0T)
  10465. ULONG currKeyRecNo;     // 280 current rec number assigned to KH.currKey
  10466. CHAR  currKey[64];      // 284 current key value
  10467. ULONG rez0;             // 348 allow for 0-terminated string
  10468. ULONG searches;         // 352 keys searched for
  10469. ULONG seeks;            // 356 nodes seeked
  10470. ULONG hits;             // 360 seeks satisfied without disk access
  10471. ULONG keysDeleted;      // 364 keys deleted since last zeroed
  10472. ULONG keysStored;       // 368 keys added since last zeroed
  10473. ULONG nodesSplit;       // 372 splits needed on insert since last zeroed
  10474. ULONG nodesMadeAvail;   // 376 nodes made available from deleting keys
  10475. ULONG lockCount;        // 380 active full-lock count
  10476.  
  10477. // the IX3 index header follows at 384+
  10478.  
  10479. Relative SDP.herePtr: 
  10480.  
  10481. ULONG fType;            // 000 bit0=1 for DBF data file, XB
  10482. ULONG flags;            // 004 bit0=1 is dirty
  10483.                         //     bit1=1 full lock
  10484.                         //     bit2=1 shared lock (if bit1=1)
  10485.                         //     bit3-15 reserved (=0)
  10486.                         // 006 BYTE, progress of pack (0,1-99)
  10487.                         // 007 BYTE, 0
  10488. PVOID morePtr;          // 008 ptr to additional header info, if ever needed
  10489. ULONG noFields;         // 012 number of fields in this data file
  10490. ULONG asMode;           // 016 access-sharing-cache mode of open
  10491. CHAR  filename[260];    // 020 filename at open (0T)
  10492. ULONG lockCount;        // 280 only when dec'ed to 0 do full unlock
  10493. ULONG memoAvailBlock;   // 284 next available block (header is block 0)
  10494. ULONG memoUnk1;         // 288 not used
  10495. CHAR  memoFilename[8];  // 292 filename proper (first 8 of filename proper)
  10496. ULONG memoUnk2;         // 300 not used (apparently)
  10497. ULONG memoBlockSize;    // 304 block size, must be at least 24 to cover header!
  10498. ULONG memoHandle;       // 308 handle of open memo file
  10499. ULONG memoFlags;        // 312 bit0=1 is dirty
  10500. ULONG memoLastNo;       // 316 last accessed memo number (if not 0)
  10501. ULONG memoLastLink;     // 320 link data for last accessed memo
  10502. ULONG memoLastSize;     // 324 size of last accessed memo (in bytes, w/OH)
  10503. ULONG align32[6];       // 328 (align to even32)
  10504.  
  10505. // the DBF data header follows at +352
  10506.  
  10507.  
  10508. ΓòÉΓòÉΓòÉ 14. Bullet Is... ΓòÉΓòÉΓòÉ
  10509.  
  10510. Bullet/2 is a thread-safe, multi-process capable database engine toolkit for 
  10511. OS/2.  It provides pre-built and tested access methods to data and index files 
  10512. for application programmers.  It is not an end-user Database Management System 
  10513. (DBMS), but it is a tool that could be used to develop one.  Bullet is compact, 
  10514. efficient, and very fast.  It can be configured to use custom key-build, 
  10515. sort-compare functions, and expression parser routines to extend the built-in 
  10516. functionality.  Rules are few; possibilities are great. 
  10517.  
  10518. The standard data format is DBF (dBASE 3+ and later).  The supported memo 
  10519. format is DBT (dBASE 4 and later).  Index-only support can be enabled and with 
  10520. this any data file format may be used (the data maintained by the programmer 
  10521. then).  Also, the DBF standard may be extended by using binary field values and 
  10522. fields larger than 255 bytes.  Index files are NLS-compatible and use an 
  10523. efficient b-tree structure.  Files may be any size supported by the OS, up to 
  10524. 4GB.  Up to 1024 files may be opened and in use by any one process, with any 
  10525. number of processes active. 
  10526.  
  10527. The Bullet API consists of a wide assortment of routines, from low-level OS 
  10528. calls to high-level transaction-list routines that can process hundreds of 
  10529. files per transaction, with roll-back on error.  Network and multi-user support 
  10530. is included, and makes use of operating system features such as atomic 
  10531. re-locking, and shared locks that allow other processes read-access to locked 
  10532. files. 
  10533.  
  10534. Bullet is simple to use, and may easily be modified by using function wrappers 
  10535. around groups of related Bullet routines.  If you don't like working with the 
  10536. parameter packs, use a wrapper and call as you like.  Bullet works the way you 
  10537. are used to working. 
  10538.  
  10539. This online manual is a complete introduction and programmer reference for 
  10540. Bullet/2.  Sample code is included, with more still on disk.  Use Bullet to 
  10541. make a mint, or at least that database program that OS/2 users are looking for. 
  10542. I'd like to, but then I wouldn't be selling Bullet to you if I were. 
  10543.  
  10544.  
  10545. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10546.  
  10547. A foreign key is a column value in one table used as a primary key in a second 
  10548. table.  For example, if one table has two fields:  employee name (primary key) 
  10549. and department code, and a second table has two fields:  department code 
  10550. (primary key) and department name, then department code in the first table is 
  10551. considered a foreign key, since it may be used as the primary key value when 
  10552. searching the second table.  Joins and views make use of foreign keys. 
  10553.  
  10554.  
  10555. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10556.  
  10557. Null pack
  10558.  
  10559.  
  10560. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10561.  
  10562. typedef struct _ACCESSPACK {
  10563. ULONG func;
  10564. ULONG stat;
  10565. ULONG handle;         /* I, handle of Bullet file to access */
  10566. LONG  recNo;          /* IO, record number */
  10567. PVOID recPtr;         /* I, programmer's record buffer */
  10568. PVOID keyPtr;         /* I, programmer's key buffer */
  10569. PVOID nextPtr;        /* I, NULL if not xaction, else next AP in list */
  10570. } ACCESSPACK; /* AP */
  10571. typedef ACCESSPACK *PACCESSPACK;
  10572.  
  10573.  
  10574. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10575.  
  10576. typedef struct _COPYPACK {
  10577. ULONG func;
  10578. ULONG stat;
  10579. ULONG handle;         /* I, handle of Bullet file to copy */
  10580. PSZ   filenamePtr;    /* I, filename to use (drv:path must exist if used) */
  10581. } COPYPACK; /* CP */
  10582. typedef COPYPACK *PCOPYPACK;
  10583.  
  10584.  
  10585. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10586.  
  10587. typedef struct _CREATEDATAPACK {
  10588. ULONG func;
  10589. ULONG stat;
  10590. PSZ   filenamePtr;    /* I, filename to use */
  10591. ULONG noFields;       /* I, 1 to 254 */
  10592. PFIELDDESCTYPE fieldListPtr;   /* I, descriptor list, 1 per field */
  10593. ULONG fileID;         /* I, 0x03 for std DBF, 0x8B for DBF+DBT */
  10594. } CREATEDATAPACK; /* CDP */
  10595. typedef CREATEDATAPACK *PCREATEDATAPACK;
  10596.  
  10597.  
  10598. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10599.  
  10600. typedef struct _CREATEINDEXPACK {
  10601. ULONG func;
  10602. ULONG stat;
  10603. PSZ   filenamePtr;    /* I, filename to use */
  10604. PSZ   keyExpPtr;      /* I, e.g., "SUBSTR(LNAME,1,4)+SSN" */
  10605. LONG  xbLink;         /* I, opened data file handle this indexes */
  10606. ULONG sortFunction;   /* I, 1-9 system, 10-19 custom */
  10607. ULONG codePage;       /* I, 0=use process default */
  10608. ULONG countryCode;    /* I, 0=use process default */
  10609. PVOID collatePtr;     /* I, NULL=use cc/cp else use passed table for sort */
  10610. ULONG nodeSize;       /* I, 512, 1024, or 2048 */
  10611. } CREATEINDEXPACK; /* CIP */
  10612. typedef CREATEINDEXPACK *PCREATEINDEXPACK;
  10613.  
  10614.  
  10615. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10616.  
  10617. typedef struct _FIELDDESCTYPE {
  10618. BYTE  fieldName[11];  /* IO, upper A-Z and _; 1-10 chars, 0-filled, 0-term */
  10619. BYTE  fieldType;      /* IO, C,D,L,N, or M */
  10620. LONG  fieldDA;        /* x, offset within record (run-time storage option) */
  10621. BYTE  fieldLen;       /* IO, C=1-255,D=8,L=1,N=1-19,M=10 */
  10622. BYTE  fieldDC;        /* IO, fieldType=N then 0-15 else 0 */
  10623. USHORT altFieldLength;/* IO, 0 */
  10624. BYTE  filler[12];     /* I, 0 */
  10625. } FIELDDESCTYPE; /* nested in DESCRIPTORPACK */
  10626. typedef FIELDDESCTYPE *PFIELDDESCTYPE;
  10627.  
  10628.  
  10629. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10630.  
  10631. typedef struct _DESCRIPTORPACK {
  10632. ULONG func;
  10633. ULONG stat;
  10634. ULONG handle;         /* I, handle of DBF file */
  10635. ULONG fieldNumber;    /* IO, first field is 1 */
  10636. ULONG fieldOffset;    /* O, offset of field within record (tag=offset 0) */
  10637. FIELDDESCTYPE FD;     /* IO FD.fieldName, O rest of FD */
  10638. } DESCRIPTORPACK; /* DP */
  10639. typedef DESCRIPTORPACK *PDESCRIPTORPACK;
  10640. };
  10641.  
  10642.  
  10643. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10644.  
  10645. typedef struct _DOSFILEPACK {
  10646. ULONG func;
  10647. ULONG stat;
  10648. PSZ   filenamePtr;    /* I, filename to use */
  10649. ULONG handle;         /* IO, handle of open file */
  10650. ULONG asMode;         /* I, access-sharing-cache mode */
  10651. ULONG bytes;          /* IO, bytes to read, write, length of */
  10652. LONG  seekTo;         /* IO, seek to offset, current offset */
  10653. ULONG method;         /* I, seek method (0=start of file, 1=current, 2=end) */
  10654. PVOID bufferPtr;      /* I, buffer to read into or write from */
  10655. ULONG attr;           /* I, attribute to create file with */
  10656. PSZ   newNamePtr;     /* I, name to use on rename */
  10657. } DOSFILEPACK; /* DFP */
  10658. typedef DOSFILEPACK *PDOSFILEPACK;
  10659.  
  10660.  
  10661. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10662.  
  10663. typedef struct _EXITPACK {
  10664. ULONG func;
  10665. ULONG stat;
  10666. } EXITPACK; /* EP */
  10667. typedef EXITPACK *PEXITPACK;
  10668.  
  10669.  
  10670. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10671.  
  10672. typedef struct _HANDLEPACK {
  10673. ULONG func;
  10674. ULONG stat;
  10675. ULONG handle;         /* I, handle of Bullet file */
  10676. } HANDLEPACK; /* HP */
  10677. typedef HANDLEPACK *PHANDLEPACK;
  10678.  
  10679.  
  10680. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10681.  
  10682. typedef struct _INITPACK {
  10683. ULONG func;
  10684. ULONG stat;
  10685. ULONG JFTsize;        /* I, max opened files (20-1024+) */
  10686. ULONG versionDOS;     /* O, e.g., 230 for 2.30 */
  10687. ULONG versionBullet;  /* O, e.g., 2019 for 2.019 */
  10688. ULONG versionOS;      /* O, e.g., 4=OS/2 32-bit */
  10689. PVOID exitPtr;        /* O, function pointer to EXIT_XB routine */
  10690. } INITPACK; /* IP */
  10691. typedef INITPACK *PINITPACK;
  10692.  
  10693.  
  10694. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10695.  
  10696. typedef struct _LOCKPACK {
  10697. ULONG func;
  10698. ULONG stat;
  10699. ULONG handle;         /* I, handle of Bullet file to lock */
  10700. ULONG xlMode;         /* I, index lock mode (0=exclusive, 1=shared) */
  10701. ULONG dlMode;         /* I, data lock mode (0=exclusive, 1=shared) */
  10702. LONG  recStart;       /* I, if data, first record # to lock, or 0 for all */
  10703. ULONG recCount;       /* I, if data and recStart!=0, # records to lock */
  10704. PVOID nextPtr;        /* I, NULL if not xaction, else next LP in list */
  10705. } LOCKPACK; /* LP */
  10706. typedef LOCKPACK *PLOCKPACK;
  10707.  
  10708.  
  10709. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10710.  
  10711. typedef struct _MEMODATAPACK {
  10712. ULONG func;
  10713. ULONG stat;
  10714. ULONG dbfHandle;      /* I, handle of DBF file to which this memo file belongs */
  10715. ULONG memoBypass;     /* I, memo bypass function to do, if any */
  10716. PVOID memoPtr;        /* I, ptr to memo record buffer */
  10717. ULONG memoNo;         /* IO, memo record number (aka block number) */
  10718. ULONG memoOffset;     /* I, position within record to start read/update */
  10719. ULONG memoBytes;      /* IO, number of bytes to read/update */
  10720. } MEMODATAPACK; /* MDP */
  10721. typedef MEMODATAPACK *PMEMODATAPACK;
  10722.  
  10723.  
  10724. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10725.  
  10726. typedef struct _MEMORYPACK {
  10727. ULONG func;
  10728. ULONG stat;
  10729. ULONG memory;         /* O, not used in OS/2 */
  10730. } MEMORYPACK; /* MP */
  10731. typedef MEMORYPACK *PMEMORYPACK;
  10732.  
  10733.  
  10734. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10735.  
  10736. typedef struct _OPENPACK {
  10737. ULONG func;
  10738. ULONG stat;
  10739. ULONG handle;         /* O, handle of file opened */
  10740. PSZ   filenamePtr;    /* I, Bullet file to open */
  10741. ULONG asMode;         /* I, access-sharing-cache mode */
  10742. LONG  xbLink;         /* I, if index open, xbLink=handle of its opened DBF */
  10743. } OPENPACK; /* OP */
  10744. typedef OPENPACK *POPENPACK;
  10745.  
  10746.  
  10747. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10748.  
  10749. typedef struct _QUERYSETPACK {
  10750. ULONG func;
  10751. ULONG stat;
  10752. ULONG item;           /* I, Bullet sysvar item to get/set */
  10753. ULONG itemValue;      /* IO, current/new value */
  10754. } QUERYSETPACK; /* QSP */
  10755. typedef QUERYSETPACK *PQUERYSETPACK;
  10756.  
  10757.  
  10758. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10759.  
  10760. typedef struct _REMOTEPACK {
  10761. ULONG func;
  10762. ULONG stat;
  10763. ULONG handle;         /* I, handle of file, or if 0, use RP.drive */
  10764. ULONG drive;          /* I, drive (1=A,2=B,3=C,...0=current) to check */
  10765. ULONG isRemote;       /* O, =1 of handle/drive is remote, =0 if local */
  10766. ULONG flags;          /* O, 0 */
  10767. ULONG isShare;        /* O, 1 */
  10768. } REMOTEPACK; /* RP */
  10769. typedef REMOTEPACK *PREMOTEPACK;
  10770.  
  10771.  
  10772. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10773.  
  10774. struct StatDataPack {
  10775. typedef struct _STATDATAPACK {
  10776. ULONG func;
  10777. ULONG stat;
  10778. ULONG handle;         /* I, handle to check */
  10779. ULONG fileType;       /* O, bit0=1 data file */
  10780. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  10781. ULONG progress;       /* O, 0,1-99% pack progress */
  10782. PVOID morePtr;        /* O, 0 */
  10783. ULONG fields;         /* O, fields per record */
  10784. ULONG asMode;         /* O, access-sharing-cache mode */
  10785. PSZ   filenamePtr;    /* O, filename used in open */
  10786. ULONG fileID;         /* O, first byte of DBF file */
  10787. ULONG lastUpdate;     /* O, high word=year,low byte=day, high byte=month */
  10788. ULONG records;        /* O, data records (including "deleted") */
  10789. ULONG recordLength;   /* O, record length */
  10790. ULONG xactionFlag;    /* O, 0 */
  10791. ULONG encryptFlag;    /* O, 0 */
  10792. PVOID herePtr;        /* O, this file's control address */
  10793. ULONG memoHandle;     /* O, handle of open memo file (0 if none) */
  10794. ULONG memoBlockSize;  /* O, memo file block size */
  10795. ULONG memoFlags;      /* O, bit0=1 dirty */
  10796. ULONG memoLastRecord; /* O, last accessed memo record (0 if none) */
  10797. ULONG memoLastSize;   /* O, size of last accessed memo record (in bytes, +8) */
  10798. ULONG lockCount;      /* O, number of full-locks in force */
  10799. } STATDATAPACK; /* SDP */
  10800. typedef STATDATAPACK *PSTATDATAPACK;
  10801.  
  10802.  
  10803. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10804.  
  10805. typedef struct _STATHANDLEPACK {
  10806. ULONG func;
  10807. ULONG stat;
  10808. ULONG handle;         /* I, handle to check */
  10809. LONG  ID;             /* O, bit0=1 data file, bit0=1 index file */
  10810. } STATHANDLEPACK; /* SHP */
  10811. typedef STATHANDLEPACK *PSTATHANDLEPACK;
  10812.  
  10813.  
  10814. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10815.  
  10816. typedef struct _STATINDEXPACK {
  10817. ULONG func;
  10818. ULONG stat;
  10819. ULONG handle;         /* I, handle to check */
  10820. ULONG fileType;       /* O, bit0=0 index file */
  10821. ULONG flags;          /* O, bit0=1 dirty, bit1=1 full-lock, bit2=1 shared */
  10822. ULONG progress;       /* O, 0,1-99% reindex progress */
  10823. PVOID morePtr;        /* O, 0 */
  10824. ULONG xbLink;         /* O, XB file link handle */
  10825. ULONG asMode;         /* O, access-sharing-cache mode */
  10826. PSZ   filenamePtr;    /* O, pointer to filename used in open */
  10827. ULONG fileID;         /* O, "31ch" */
  10828. PSZ   keyExpPtr;      /* O, pointer to key expression */
  10829. ULONG keys;           /* O, keys in file */
  10830. ULONG keyLength;      /* O, key length */
  10831. ULONG keyRecNo;       /* O, record number of current key */
  10832. PVOID keyPtr;         /* O, ptr to current key value (valid to keyLength) */
  10833. PVOID herePtr;        /* O, this file's control address */
  10834. ULONG codePage;       /* O, code page at create time */
  10835. ULONG countryCode;    /* O, country code at create time */
  10836. PVOID CTptr;          /* O, collate table ptr, NULL=no collate table present */
  10837. ULONG nodeSize;       /* O, node size */
  10838. ULONG sortFunction;   /* O, sort function ID */
  10839. ULONG lockCount;      /* O, number of full-locks in force */
  10840. } STATINDEXPACK; /* SIP */
  10841. typedef STATINDEXPACK *PSTATINDEXPACK;
  10842.  
  10843.  
  10844. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10845.  
  10846. typedef struct _XERRORPACK {
  10847. ULONG func;
  10848. ULONG stat;           /* I, error to check */
  10849. ULONG errClass;       /* O, class of error */
  10850. ULONG action;         /* O, action recommended for error */
  10851. ULONG location;       /* O, location of error */
  10852. } XERRORPACK; /* XEP */
  10853. typedef XERRORPACK *PXERRORPACK;
  10854.  
  10855.  
  10856. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10857.  
  10858.  Access-Mode (required)
  10859.   READONLY        0x00000000   read-only access open
  10860.   WRITEONLY       0x00000001   write-only access open
  10861.   READWRITE       0x00000002   read/write access open
  10862.  
  10863.  Share-Mode (required)
  10864.   DENYREADWRITE   0x00000010   no other process may share file
  10865.   DENYWRITE       0x00000020   no other process may share file for write
  10866.   DENYREAD        0x00000030   no other process may share file for read
  10867.   DENYNONE        0x00000040   any process may share file
  10868.  
  10869.  Inherit
  10870.   NOINHERIT       0x00000080   child process does not inherit file handles
  10871.  
  10872.  Cache
  10873.   NO_LOCALITY     0x00000000  locality is not known
  10874.   SEQ_LOCALITY    0x00010000  access will be mainly sequential
  10875.   RND_LOCALITY    0x00020000  access will be mainly random
  10876.   MIX_LOCALITY    0x00030000  access will be random with some sequential
  10877.   SKIP_CACHE      0x00100000  I/O is not to go through the cache
  10878.   WRITE_THROUGH   0x00400000  control returns only after disk is written to
  10879.  
  10880. Access- and Share-Mode values not explicitly listed are not valid.  The file 
  10881. access mode is a combination of ACCESS + SHARE + INHERIT + CACHE.  Typical data 
  10882. and index asMode is 0x00000042, though locality may be set accordingly (e.g., 
  10883. 0x00020042 for mostly random access to the file). 
  10884.  
  10885. The Cache mode options are valid for OPEN_DATA_XB and OPEN_INDEX_XB only; for 
  10886. DOS_FILE_OPEN, the Cache values must be right-shifted by 8.  The 'Skip Cache' 
  10887. and 'Write Through' options are not inherited. 
  10888.  
  10889.  
  10890. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10891.  
  10892. The enumerator is a big-endian 16-bit value that serves to differentiate up to 
  10893. 65536 "identical", non- unique keys.  It is attached to all keys of 
  10894. DUPS_ALLOWED flagged index files (set at CREATE_INDEX_XB), and occupies the 
  10895. last two bytes of the key.  The first key of the type uses \0\0, the second 
  10896. uses \0\1, and so on.  This ordering of bytes is the reverse of x86 Intel 
  10897. words, which uses little-endian format. 
  10898.  
  10899.  
  10900. ΓòÉΓòÉΓòÉ <hidden>  ΓòÉΓòÉΓòÉ
  10901.  
  10902. HIGH-VALUES signify a sort order so that the value is the highest possible 
  10903. (sorts last).  HIGH-VALUES for a character key would be 0xFF for each byte, or 
  10904. the 256th byte of the collate-sequence table if an NLS sort (which is 0xFF 
  10905. also).  For 16-bit signed integer values, 0x7FFF is the highest.  And so on...